Add troubleshooting guide to docs (#655)

docs/contact/index.md

@@ -11,4 +11,4 @@ If you need help or have any questions about installing or using AliasVault, you
 
 If you have found a bug or have a feature request, please open an issue on [AliasVault GitHub](https://github.com/lanedirt/AliasVault/issues).
 
-If you have any other questions or feedback, please use the contact form on the [AliasVault website](https://aliasvault.net/contact).
+If you have any other questions or feedback, please visit the contact page on the [AliasVault website](https://aliasvault.net/contact).

docs/index.md

@@ -9,7 +9,8 @@ permalink: /
 # AliasVault Documentation
 {: .fs-9 }
 
-Open-source password and identity manager with email alias generation and zero-knowledge architecture.
+Open-source E2EE password and alias manager with built-in email server and zero-knowledge architecture.
+
 {: .fs-6 .fw-300 }
 
 [Installation](./installation/install){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
@@ -19,7 +20,7 @@ Open-source password and identity manager with email alias generation and zero-k
 
 ## What is AliasVault?
 
-AliasVault is a self-hosted password and identity manager that helps you:
+AliasVault is a self-hosted password and (email) alias manager that helps you:
 
 - 🔐 **Secure Passwords** - Store and manage passwords with zero-knowledge encryption
 - 📧 **Email Aliases** - Generate unique email addresses for each service

docs/installation/advanced/manual-setup.md

@@ -172,4 +172,4 @@ If you encounter any issues during the setup:
    docker compose logs postgres
    ```
 
-For further assistance, please refer to the project documentation or seek support through the appropriate channels.
+For more detailed troubleshooting information, please refer to the full [troubleshooting guide](../troubleshooting.md).

docs/installation/install.md

@@ -158,21 +158,11 @@ If you want to entirely disable IP logging, you can do so by running the install
 
 ## 6. Troubleshooting
 
-### Resetting the admin password
-If you have lost your admin password, you can reset it by running the install script with the `reset-password` option. This will generate a new random password and update the .env file with it. After that it will restart the AliasVault containers to apply the changes.
-```bash
-./install.sh reset-password
-```
-
 ### Verbose output
 If you need more detailed output from the install script, you can run it with the `--verbose` option. This will print more information to the console.
 ```bash
 ./install.sh install --verbose
 ```
 
-### No emails being received
-If you are not receiving emails on your aliases, check the following:
-- Verify DNS records are correctly configured
-- Ensure ports 25 and 587 are accessible
-- Check your server's firewall settings
-- Verify that your ISP/hosting provider allows SMTP traffic
+### Troubleshooting guide
+For more detailed troubleshooting information, please refer to the [troubleshooting guide](./troubleshooting.md).

docs/installation/troubleshooting.md

@@ -0,0 +1,116 @@
+---
+layout: default
+title: Troubleshooting
+parent: Installation Guide
+nav_order: 5
+---
+
+# Troubleshooting
+
+This guide covers common issues and troubleshooting steps for AliasVault encountered during installation, updates or general maintenance.
+
+{: .toc }
+* TOC
+{:toc}
+
+---
+
+## Check Docker Container Status
+For any issues you might encounter, the first step is to check the Docker containers health. This will give you a quick insight into the status of the individual containers which will help you identify the root cause of the issue.
+
+1. List all running containers and their status (execute from the AliasVault installation directory):
+```bash
+docker compose ps
+```
+
+2. Check the logs of a specific container.
+```
+docker compose logs [container-name-here]]
+```
+> Possible container names: `api`, `postgres`, `client`, `admin`, `reverse-proxy`, `smtp`, `task-runner`
+
+3. In order to restart a specific container, run the following command:
+```bash
+docker compose restart [container-name-here]
+```
+
+4. In order to restart the whole AliasVault stack, do not use docker compose directly, but run the following command instead. This makes sure the correct `docker-compose.yml` file is being used:
+```bash
+./install.sh restart
+```
+
+---
+
+## Check AliasVault Text Logs
+All AliasVault services log information and errors to text files. These files are located in the `logs` directory. You can check the logs of a specific container by running the following command:
+
+```bash
+cat logs/[container-name-here].log
+```
+
+---
+
+## Common Issues
+Below are some common issues you might encounter and how to troubleshoot them.
+
+### 1. Database Connection Issues
+
+**Symptoms:**
+- API, Admin, or SMTP services failing to start
+- Database connection errors in logs
+
+**Steps:**
+1. Check if PostgreSQL container is running:
+```bash
+docker compose ps
+```
+
+2. Check the logs of the PostgreSQL container:
+```bash
+docker compose logs postgres
+```
+
+### 2. SSL Certificate Issues
+
+**Symptoms:**
+- Browser shows SSL errors
+
+**Steps:**
+1. Check the certbot container logs if SSL certificates are being correctly renewed:
+```bash
+docker compose logs certbot
+```
+
+2. Check the logs of the reverse-proxy container:
+```bash
+docker compose logs reverse-proxy
+```
+
+3. In case the SSL certificates are being correctly renewed, but the browser still shows SSL errors, try to restart AliasVault manually in order to force the NGINX container to reload the SSL certificates:
+```bash
+./install.sh restart
+```
+
+### 3. No emails being received
+If you are not receiving emails on your aliases, check the following:
+- Verify DNS records are correctly configured
+- Ensure ports 25 and 587 are accessible
+- Check your server's firewall settings
+- Verify that your ISP/hosting provider allows SMTP traffic
+
+Refer to the [installation guide](./install.md) for more information on how to configure your DNS records and ports.
+
+
+### 4. Forgot AliasVault Admin Password
+If you have lost your admin password, you can reset it by running the install script with the `reset-password` option. This will generate a new random password and update the .env file with it. After that it will restart the AliasVault containers to apply the changes.
+
+```bash
+./install.sh reset-password
+```
+
+---
+
+## Other Issues
+If you encounter any other issues not mentioned here and need help, please join our Discord server or create an issue on the GitHub repository and we will be happy to help you out.
+
+Find all contact information on the contact page of our website: [https://aliasvault.net/contact](https://aliasvault.net/contact)