document common troubleshooting steps

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.
+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.

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.