From 271e63c96072efd2784cdcd8e3ee67a7b82b5b8d Mon Sep 17 00:00:00 2001
From: Massaki Archambault <marchambault@badjware.dev>
Date: Sun, 29 Dec 2024 18:16:23 -0500
Subject: [PATCH] document common troubleshooting steps

---
 README.md           | 22 +++++++++++++++++++++-
 config.example.yaml |  5 ++++-
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 44255a5..d21fd8a 100644
--- a/README.md
+++ b/README.md
@@ -92,4 +92,24 @@ While the filesystem lives in memory, the git repositories that are cloned are s
 
 Simply use `make` to create the executable. The executable will be in `bin/`.
 
-See `make help` for all available targets.
\ No newline at end of file
+See `make help` for all available targets.
+
+## Troubleshooting
+
+### My application claims that a file or a folder doesn't exists.
+
+Some applications doesn't resolve symlinks properly. Try setting the `fs.use_symlinks` configuration to `false`.
+
+### `docker` fails to run with the message _error while creating mount source path_
+
+This happens because `docker` is running as a different user than the one who created the mount. Follow these steps to allow docker access to the mount:
+
+1. Open the file `/etc/fuse.conf` as root.
+2. Add `user_allow_other` to the file, then close and save your modifications.
+3. Open your `gitforgefs` configuration.
+4. Add the `allow_other` to your mountoptions. The mount option are configured in `fs.mountoptions`.
+``` yaml
+fs:
+  mountoptions: allow_other,nodev,nosuid
+```
+5. Restart your mount.
diff --git a/config.example.yaml b/config.example.yaml
index 2925b97..ff5e847 100644
--- a/config.example.yaml
+++ b/config.example.yaml
@@ -3,11 +3,14 @@ fs:
   #mountpoint: /mnt
 
   # Mount options to pass to `fusermount` as its `-o` argument. Can be overwritten via the command line.
+  # Some applications need the `allow_other` option to function properly (eg: docker). If you need to use `allow_other`,
+  # you must also add `user_allow_other` in /etc/fuse.conf.
   # See mount.fuse(8) for the full list of options.
   #mountoptions: nodev,nosuid
+  #mountoptions: allow_other,nodev,nosuid
 
   # Use a symlink to point to the real location of the repository instead of doing a loopback
-  # Faster and allow cloning to be asynchronous, but may cause compatibility issues
+  # Using symlinks is more performant and allow cloning to be asynchronous, but may cause compatibility issues with some applications
   # use_symlinks: false
 
   # The git forge to use as the backend.