docs: update troubleshooting guide

Signed-off-by: Varun Patil <radialapps@gmail.com>

.github/ISSUE_TEMPLATE/bug_report.md

@@ -6,22 +6,23 @@ labels: needs triage
 assignees: ''
 ---
 
+<!--
+
 **🛑 READ THE FOLLOWING BEFORE YOU CONTINUE! 🛑**
 
-All bugs _must_ follow the issue template below, or they will be closed without triage.  
-If it is a help request, you might want to try the [Discord community](https://discord.gg/7Dr9f9vNjJ) first.  
+All bug reports *must* follow the issue template below.
+
+If it is a help request, you might want to try the [Discord community](https://discord.gg/7Dr9f9vNjJ) first.
+
 Make the following items are true before filing a bug:
 
 - You are using the latest version of the app.
 - You tried and can replicate the bug.
-- The problem persists after clearing browser cache.
 - You have followed the [configuration steps](https://memories.gallery/config/).
+- You have looked at the [troubleshooting](https://memories.gallery/troubleshooting/) documentation.
 - You have searched the [open issues](https://github.com/pulsejet/memories/issues)
-- You are NOT using `OCCWeb` to run `occ` commands
 
-If you are sure the above is true, _remove this section_ and fill in the template below.
-
----
+-->
 
 **Describe the bug**
 A clear and concise description of what the bug is.

docs/faq.md

@@ -54,7 +54,7 @@ UX and performance. The devil is in the details.
 
 **It's slow or doesn't work**
 
-Make sure you follow the [configuration steps](../config). Unless you have hundreds of thousands of photos on a Raspberry Pi, Memories should be very fast. File an issue otherwise.
+Make sure you follow the [troubleshooting steps](../troubleshooting/#performance). Unless you have hundreds of thousands of photos on a Raspberry Pi, Memories should be very fast. File an issue otherwise.
 
 **It says "nothing to show here" on startup?**
 
@@ -64,24 +64,3 @@ the [configuration steps](../config) and be patient.
 **Will it run on my system?**
 
 In general, if you can run Nextcloud, you should be able to run Memories. File an issue if you run into problems.
-
-**How to completely remove Memories? Maybe to reinstall after errors?**
-
-Uninstall Memories from the app store, then run the following SQL on your database.
-
-```sql
-DROP TABLE IF EXISTS oc_memories;
-DROP TABLE IF EXISTS oc_memories_livephoto;
-DROP TABLE IF EXISTS oc_memories_mapclusters;
-DROP TABLE IF EXISTS oc_memories_places;
-DROP TABLE IF EXISTS oc_memories_planet;
-DROP TABLE IF EXISTS memories_planet_geometry;
-DROP INDEX IF EXISTS memories_parent_mimetype ON oc_filecache;
-DELETE FROM oc_migrations WHERE app='memories';
-```
-
-On Postgres, the syntax for dropping the index is:
-
-```sql
-DROP INDEX IF EXISTS memories_parent_mimetype;
-```

docs/troubleshooting.md

@@ -0,0 +1,74 @@
+---
+description: Solutions to common problems
+---
+
+# Troubleshooting
+
+This page contains solutions to common problems. If you are facing any issues, please refer to this page before opening an issue.
+
+## Performance
+
+Memories is very fast, but its performance largely depends on how well the Nextcloud instance is tuned. Make sure to follow the following steps:
+
+- Make sure you are running the latest stable version of Nextcloud and Memories.
+- Follow the steps in the [server tuning](https://docs.nextcloud.com/server/latest/admin_manual/installation/server_tuning.html) documentation.
+- Follow all configuration steps in the [configuration](../config) documentation.
+
+      - Disable video transcoding if your server is not powerful enough.
+      - Reduce the maximum size of previews to be generated.
+
+- Make sure you are running HTTPS (very important).
+- Enable HTTP/2 or HTTP/3 on your server.
+- Enable and configure PHP Opcache and JIT.
+- Enable and configure the APCu cache.
+- Enable and configure Redis for transactional file locking.
+- Enable gzip compression on your HTTP server for static assets (CSS/JS).
+
+## No photos are shown
+
+This means that Memories is unable to find any indexed photos in your Nextcloud instance. Make sure you have followed the [configuration steps](../config). Note that Memories indexes photos in the background, so it may take a while for the photos to show up. Ensure that Nextcloud's cron system is properly configured and running.
+
+## Issues with Docker
+
+Note: Using the official Nextcloud Docker image is the recommended way of running Memories. If you are using a different image, you may run into issues.
+
+### OCC commands fail
+
+The most common reason for this is a missing interactive TTY. Make sure you run the commands with `-it`:
+
+```bash
+docker exec -it my_nc_container php occ memories:index
+#           ^^^  <-- this is required
+```
+
+### Usage of tmpfs
+
+If you are using `tmpfs` (e.g. for the Recognize app), make sure the temp directory is set to executable. With Docker compose, your `docker-compose.yml` should look like this:
+
+```yaml
+app:
+    ...
+    tmpfs:
+    - /tmp:exec
+```
+
+## Reset
+
+If you want to completely reset Memories (e.g. for database trouble), uninstall it from the app store, then run the following SQL on your database to clean up any data.
+
+```sql
+DROP TABLE IF EXISTS oc_memories;
+DROP TABLE IF EXISTS oc_memories_livephoto;
+DROP TABLE IF EXISTS oc_memories_mapclusters;
+DROP TABLE IF EXISTS oc_memories_places;
+DROP TABLE IF EXISTS oc_memories_planet;
+DROP TABLE IF EXISTS memories_planet_geometry;
+DROP INDEX IF EXISTS memories_parent_mimetype ON oc_filecache; /* MySQL */
+DELETE FROM oc_migrations WHERE app='memories';
+```
+
+On Postgres, the syntax for dropping the index is:
+
+```sql
+DROP INDEX IF EXISTS memories_parent_mimetype;
+```

mkdocs.yml

@@ -42,6 +42,7 @@ nav:
       - 'config.md'
       - 'file-types.md'
       - 'hw-transcoding.md'
+      - 'troubleshooting.md'
       - 'system-config.md'
   - Support:
       - 'faq.md'