From 1bcd0887826558bedafd07e278f0258d78c38f5d Mon Sep 17 00:00:00 2001 From: Leendert de Borst Date: Sat, 6 Sep 2025 20:50:49 +0200 Subject: [PATCH] Add advanced and troubleshooting steps per self-host method (#1181) --- .vscode/tasks.json | 2 +- docs/_config.yml | 3 + docs/_sass/color_schemes/aliasvault.scss | 6 + docs/installation/index.md | 28 ++-- .../install.sh/advanced/database.md | 22 --- .../installation/install.sh/advanced/index.md | 14 -- .../advanced/reverse-proxy-configuration.md | 141 ------------------ .../advanced/build-from-source.md | 1 + .../installer/advanced/database.md | 25 ++++ docs/installation/installer/advanced/index.md | 9 ++ .../advanced/lifecycle.md} | 7 +- .../installer/advanced/uninstall.md | 20 +++ .../{install.sh => installer}/index.md | 35 ++--- .../troubleshooting.md | 6 +- .../{install.sh => installer}/update/index.md | 2 +- .../update/v0.22.0.md | 0 docs/installation/manual-setup.md | 139 ----------------- docs/installation/manual/advanced/database.md | 25 ++++ docs/installation/manual/advanced/index.md | 9 ++ .../installation/manual/advanced/lifecycle.md | 30 ++++ .../advanced/uninstall.md | 1 + docs/installation/{docker => manual}/index.md | 42 +++--- docs/installation/manual/troubleshooting.md | 82 ++++++++++ 23 files changed, 271 insertions(+), 378 deletions(-) delete mode 100644 docs/installation/install.sh/advanced/database.md delete mode 100644 docs/installation/install.sh/advanced/index.md delete mode 100644 docs/installation/install.sh/advanced/reverse-proxy-configuration.md rename docs/installation/{install.sh => installer}/advanced/build-from-source.md (95%) create mode 100644 docs/installation/installer/advanced/database.md create mode 100644 docs/installation/installer/advanced/index.md rename docs/installation/{install.sh/advanced/start-stop.md => installer/advanced/lifecycle.md} (76%) create mode 100644 docs/installation/installer/advanced/uninstall.md rename docs/installation/{install.sh => installer}/index.md (84%) rename docs/installation/{install.sh => installer}/troubleshooting.md (96%) rename docs/installation/{install.sh => installer}/update/index.md (97%) rename docs/installation/{install.sh => installer}/update/v0.22.0.md (100%) delete mode 100644 docs/installation/manual-setup.md create mode 100644 docs/installation/manual/advanced/database.md create mode 100644 docs/installation/manual/advanced/index.md create mode 100644 docs/installation/manual/advanced/lifecycle.md rename docs/installation/{install.sh => manual}/advanced/uninstall.md (92%) rename docs/installation/{docker => manual}/index.md (82%) create mode 100644 docs/installation/manual/troubleshooting.md diff --git a/.vscode/tasks.json b/.vscode/tasks.json index 66d0259e0..89e6b2fa4 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -199,7 +199,7 @@ { "label": "Build and watch Docs", "type": "shell", - "command": "docker compose up", + "command": "docker compose build && docker compose up", "problemMatcher": [], "group": { "kind": "build", diff --git a/docs/_config.yml b/docs/_config.yml index 1d25a0ea5..49a75843d 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -38,3 +38,6 @@ callouts: note: title: Note color: purple + important: + title: Important + color: yellow diff --git a/docs/_sass/color_schemes/aliasvault.scss b/docs/_sass/color_schemes/aliasvault.scss index 2f8d0783f..2fe8b0cb0 100644 --- a/docs/_sass/color_schemes/aliasvault.scss +++ b/docs/_sass/color_schemes/aliasvault.scss @@ -38,5 +38,11 @@ $purple-100: #ffd5a8; $purple-200: #f49541; $purple-300: #d68338; +// Orange Colors +$orange-000: #f8b963; +$orange-100: #ffd5a8; +$orange-200: #f49541; +$orange-300: #d68338; + // Navigation additional $nav-button-color: #f49541; diff --git a/docs/installation/index.md b/docs/installation/index.md index c82bdd4fb..a311978d5 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -8,18 +8,18 @@ nav_order: 2 AliasVault can be self-hosted on your own servers using two different installation methods. Both use Docker, but they differ in how much is automated versus how much you manage yourself: -[Option 1: Install.sh](./installation/install){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } -[Option 2: All-In-One Docker Image](https://github.com/aliasvault/aliasvault){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 } - --- -## Option 1: `install.sh` (Managed Multi-Container Stack) +## Option 1: Installer Script (multi-container) + +[Install AliasVault via installer script (multi-container)](./installer){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } > **Best for:** > - VM or LXC (Proxmox, DigitalOcean Droplet, VPS, AWS/Azure VM) -> - Any other host that is directly accessible from the internet and/or has ports 80/443 forwarded to it, **without existing SSL termination** +> - Any other host that is directly accessible from the internet and/or has ports 80/443 forwarded to it +> - When you don't have any SSL termination proxy of your own (yet) -This option installs the **full AliasVault stack** (client, API, Postgres, task runner, SMTP, admin, reverse proxy) as multiple Docker containers in the background. +This option installs the full AliasVault stack **consisting of multiple Docker containers** (client, api, ppostgres, task runner, smtp, admin, reverse proxy) in the background. The `install.sh` script provides: - **Automatic configuration of docker-compose.yml with multiple containers** @@ -29,18 +29,18 @@ The `install.sh` script provides: - Allows to build Docker containers from source (optional) - Opinionated defaults for a secure, production-ready setup -[Installation guide →](install-vm.md) - --- -## Option 2: All-in-One Docker Image +## Option 2: Manual Setup (single container) + +[Install AliasVault via manual setup (single container)](./manual){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 } + > **Best for:** -> - Home servers / NAS (Synology, Unraid, Raspberry Pi, local Docker) -> - Advanced users with their own SSL termination (Traefik, Nginx, HAProxy, Caddy, etc.) -> - Environments where AliasVault runs **behind an existing reverse proxy** +> - Single home servers / NAS (Synology, Unraid, Raspberry Pi, local Docker) +> - Advanced users with existing shared SSL infrastructure (Traefik, Nginx, HAProxy, Caddy, etc.) -This option runs AliasVault as a **single bundled container** (client, API, Postgres, task runner, SMTP, etc. included). +This option runs AliasVault as a **single bundled Docker container** (client, API, Postgres, task runner, SMTP, etc. included). Everything is managed via **standard Docker commands**: - Updates are done manually with `docker pull` @@ -50,5 +50,3 @@ Everything is managed via **standard Docker commands**: 👉 Use this option if you **already manage SSL**, have an existing host where you are running other Docker apps already, and/or prefer to run AliasVault behind your own reverse proxy setup. - -[Docker guide →](install-docker.md) diff --git a/docs/installation/install.sh/advanced/database.md b/docs/installation/install.sh/advanced/database.md deleted file mode 100644 index 8f4c2b7b6..000000000 --- a/docs/installation/install.sh/advanced/database.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -layout: default -title: Database Backup -parent: Advanced -nav_order: 4 ---- - -# Database Backup - -In order to backup the database, you can use the `install.sh` script. This script will stop all services, export the database to a file, and then restart the services. - -```bash -./install.sh db-backup > backup.sql.gz -``` - -# Database Restore - -To restore the database, you can use the `install.sh` script. This script will stop all services, drop the database, import the database from a file, and then restart the services. - -```bash -./install.sh db-restore < backup.sql.gz -``` diff --git a/docs/installation/install.sh/advanced/index.md b/docs/installation/install.sh/advanced/index.md deleted file mode 100644 index bd27e1b60..000000000 --- a/docs/installation/install.sh/advanced/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: default -title: Advanced -parent: Install.sh -nav_order: 4 ---- - -# Advanced Installation -The following guides provide more advanced installation options for AliasVault. These options are not required for the basic installation, but may be useful for advanced users. - -- [Manual Setup](manual-setup.md) - Step-by-step manual installation without the install script -- [Reverse Proxy Configuration](reverse-proxy-configuration.md) - Configure AliasVault with your existing reverse proxy -- [Build from Source](build-from-source.md) - Build AliasVault from source code -- [Database Configuration](database.md) - Advanced database configuration options diff --git a/docs/installation/install.sh/advanced/reverse-proxy-configuration.md b/docs/installation/install.sh/advanced/reverse-proxy-configuration.md deleted file mode 100644 index 570a5e380..000000000 --- a/docs/installation/install.sh/advanced/reverse-proxy-configuration.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -layout: default -title: Reverse Proxy Configuration -parent: Advanced -nav_order: 2 ---- - -# Reverse Proxy Configuration -This guide is intended for users who already have a self-hosted reverse proxy setup (such as nginx, Apache, or Cloudflare Tunnel) and want to expose AliasVault through it. In this case, the recommended approach is to forward a single hostname (e.g., `aliasvault.example.com`) to the internal reverse proxy container that AliasVault provides. - -If you do **not** already have an existing reverse proxy, you can simply rely on the built-in reverse proxy that comes with AliasVault, as it's fully capable of handling all routing, SSL termination, and WebSocket support out of the box. - - -## Overview -AliasVault includes its own internal reverse proxy (nginx) that handles routing between its three core services: -- **Client Application** (`/`) – The main user interface -- **API Server** (`/api`) – REST API endpoints -- **Admin Panel** (`/admin`) – Administrative interface - -When using an external reverse proxy, you **must** forward requests to the `reverse-proxy` container. Do **not** route traffic directly to the individual services. - -## Why AliasVault Uses Its Own Reverse Proxy -AliasVault’s internal reverse proxy ensures proper routing and configuration of all services under one domain: - -1. **Unified Hostname** – All services operate under the same domain (e.g., `aliasvault.example.com`) -2. **Path-Based Routing** – Correct dispatch of `/`, `/api`, and `/admin` requests -3. **Security Headers** – Consistent headers across services -4. **SSL Termination** – Central SSL/TLS handling -5. **WebSocket Support** – Required for the Blazor-based admin interface - -## Internal Nginx Configuration Structure -AliasVault's reverse proxy follows a path-based routing configuration like this: - -```nginx -# Upstream services -upstream client { - server client:3000; -} -upstream api { - server api:3001; -} -upstream admin { - server admin:3002; -} - -server { - listen 443 ssl; - server_name _; - - location /admin { - proxy_pass http://admin; - # WebSocket support and headers - } - - location /api { - proxy_pass http://api; - } - - location / { - proxy_pass http://client; - } -} -``` - -## Simplest Setup (Recommended) -Forward all traffic from your external reverse proxy to the AliasVault internal reverse proxy container. This avoids manual path-based routing. - -### Example: External Nginx Reverse Proxy - -```nginx -server { - listen 80; - server_name aliasvault.example.com; - return 301 https://$host$request_uri; -} - -server { - listen 443 ssl; - server_name aliasvault.example.com; - - ssl_certificate /path/to/your/certificate.crt; - ssl_certificate_key /path/to/your/private.key; - - location / { - proxy_pass https://aliasvault-internal:443; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - } -} -``` - -## Port Configuration -AliasVault’s internal reverse proxy defaults to port `443`. If this port is already in use, you can change it in the `.env` file inside your AliasVault folder: - -``` -HTTP_PORT=80 -HTTPS_PORT=443 -``` - -Make sure your external proxy points to the correct port. - -## Common Issues and Solutions - -### HTTP 502 Bad Gateway - -**Cause**: External proxy routing to wrong container. -**Fix**: Ensure it routes to `reverse-proxy` container, not `client`, `api`, or `admin`. - -### WebSocket Errors - -**Cause**: WebSocket headers not forwarded. -**Fix**: Make sure `Upgrade` and `Connection` headers are preserved. - -### SSL/TLS Verification (e.g., Cloudflare Tunnel) - -**Cause**: TLS verification fails. -**Fix**: Enable “No TLS Verify” in your Cloudflare Tunnel configuration. - -### Partial Routing Failures - -**Cause**: External proxy modifies paths. -**Fix**: Do not strip or rewrite paths. Proxy should pass `/`, `/api`, `/admin` as-is. - -## Testing -After setup, verify: - -- `https://your-domain.com/` loads the client app -- `https://your-domain.com/api` returns OK -- `https://your-domain.com/admin` loads the admin interface - -All services must be available under the **same** hostname. - -## Security Considerations -- Always use HTTPS in production -- Preserve headers like `X-Real-IP`, `X-Forwarded-For` -- Consider adding rate limiting or IP restrictions on your external proxy -- Keep certificates and secrets secure - -For advanced scenarios or troubleshooting, refer to the main [troubleshooting guide](../troubleshooting.md). diff --git a/docs/installation/install.sh/advanced/build-from-source.md b/docs/installation/installer/advanced/build-from-source.md similarity index 95% rename from docs/installation/install.sh/advanced/build-from-source.md rename to docs/installation/installer/advanced/build-from-source.md index 4a832d7d3..a35eb09f5 100644 --- a/docs/installation/install.sh/advanced/build-from-source.md +++ b/docs/installation/installer/advanced/build-from-source.md @@ -2,6 +2,7 @@ layout: default title: Build from Source parent: Advanced +grand_parent: Installer Script (multi-container) nav_order: 3 --- diff --git a/docs/installation/installer/advanced/database.md b/docs/installation/installer/advanced/database.md new file mode 100644 index 000000000..1cd0c67fa --- /dev/null +++ b/docs/installation/installer/advanced/database.md @@ -0,0 +1,25 @@ +--- +layout: default +title: Database Operations +parent: Advanced +grand_parent: Installer Script (multi-container) +nav_order: 4 +--- + +# Database Operations +This page explains how to import/export on the AliasVault server database via the `./install.sh` script. + +## Database Export +In order to backup the AliasVault server database (which includes all encrypted user vaults as well), you can use the `install.sh` script. This script will stop all services, export the database to a file, and then restart the services. + +```bash +./install.sh db-backup > backup.sql.gz +``` + +## Database Import + +To restore a previously exported database, you can use the `install.sh` script. This script will stop all services, drop the database, import the database from a file, and then restart the services. + +```bash +./install.sh db-restore < backup.sql.gz +``` diff --git a/docs/installation/installer/advanced/index.md b/docs/installation/installer/advanced/index.md new file mode 100644 index 000000000..14aacec44 --- /dev/null +++ b/docs/installation/installer/advanced/index.md @@ -0,0 +1,9 @@ +--- +layout: default +title: Advanced +parent: Installer Script (multi-container) +nav_order: 4 +--- + +# Advanced Installation +The following guides provide more advanced installation options for AliasVault. These options are not required for the basic installation, but may be useful for advanced users. diff --git a/docs/installation/install.sh/advanced/start-stop.md b/docs/installation/installer/advanced/lifecycle.md similarity index 76% rename from docs/installation/install.sh/advanced/start-stop.md rename to docs/installation/installer/advanced/lifecycle.md index 2d7c1a30b..abea31f63 100644 --- a/docs/installation/install.sh/advanced/start-stop.md +++ b/docs/installation/installer/advanced/lifecycle.md @@ -1,12 +1,13 @@ --- layout: default -title: Start/stop +title: Stop/start parent: Advanced +grand_parent: Installer Script (multi-container) nav_order: 2 --- -# Starting and stopping AliasVault -You can start and stop AliasVault easily by using the install script. +# Stopping and starting AliasVault +You can stop and start AliasVault easily by using the install script. ## Stop To stop AliasVault, run the install script with the `stop` option. This will stop all running AliasVault containers. diff --git a/docs/installation/installer/advanced/uninstall.md b/docs/installation/installer/advanced/uninstall.md new file mode 100644 index 000000000..665361129 --- /dev/null +++ b/docs/installation/installer/advanced/uninstall.md @@ -0,0 +1,20 @@ +--- +layout: default +title: Uninstall +parent: Advanced +grand_parent: Installer Script (multi-container) +nav_order: 4 +--- + +# Uninstall + +To uninstall AliasVault, run the install script with the `uninstall` option. This will stop and remove the AliasVault containers, remove the Docker images, and delete the .env file. + +{: .note } +This will not delete any data stored in the database. If you wish to delete all data, you should manually delete the `database` directory and the other directories created by AliasVault. + +### Steps +1. Run the install script with the `uninstall` option +```bash +./install.sh uninstall +``` diff --git a/docs/installation/install.sh/index.md b/docs/installation/installer/index.md similarity index 84% rename from docs/installation/install.sh/index.md rename to docs/installation/installer/index.md index 13802e019..8449663ef 100644 --- a/docs/installation/install.sh/index.md +++ b/docs/installation/installer/index.md @@ -1,28 +1,26 @@ --- layout: default -title: Installer Script (managed) +title: Installer Script (multi-container) parent: Self-hosting nav_order: 1 --- -# Self-host via install.sh +# Self-host using installer script (multi-container) The following guide will walk you through the steps to install AliasVault on your own server using the AliasVault installer script: `install.sh`. Minimum experience with Docker and Linux is required. Estimated time: 5-15 minutes. -{: .toc } -* TOC -{:toc} +{: .important-title } +> Requirements: +> - 64-bit Linux VM with root access (Ubuntu or RHEL-based recommended) +> - Minimum: 1 vCPU, 1GB RAM, 16GB disk +> - Docker (CE ≥ 20.10) and Docker Compose (≥ 2.0) +> → Installation guide: [Docker Docs](https://docs.docker.com/engine/install/) +> - Able to forward ports 80, 443 (with optional 25/587 for private email domains) --- ## 1. Basic Installation To get AliasVault up and running quickly, run the install script to pull pre-built Docker images. The install script will also configure the .env file and start the AliasVault containers. You can get up and running in less than 5 minutes. -### Hardware requirements -- 64-bit Linux VM with root access (Ubuntu or RHEL-based recommended) -- Minimum: 1 vCPU, 1GB RAM, 16GB disk -- Docker (CE ≥ 20.10) and Docker Compose (≥ 2.0) - → Installation guide: [Docker Docs](https://docs.docker.com/engine/install/) - ### Installation steps 1. Download the install script to a directory of your choice. All AliasVault files and directories will be created in this directory. ```bash @@ -50,9 +48,9 @@ chmod +x install.sh --- ## 2. SSL configuration -The default installation will create a self-signed SSL certificate and configure Nginx to use it. +The default installation will create a self-signed SSL certificate and configure Nginx to use it. This is sufficient for local deployments using only the web-app, however the mobile apps (iOS and Android) require a valid (external) SSL certificate to be able to connect. -You can however also use Let's Encrypt to generate valid SSL certificates and configure Nginx to use it. In order to make this work you will need the following: +To generate a valid external SSL certificate for AliasVault, you can use Let's Encrypt via a built-in helper tool. In order to make this work you will need the following: - A public IPv4 address assigned to your server - Port 80 and 443 on your server must be open and accessible from the internet @@ -76,19 +74,18 @@ and then in the prompt choose option 2. AliasVault includes a built-in email server that allows you to generate email aliases on-the-fly for every website you use, and receive + read the emails straight in AliasVault. -> **Note:** -> If you skip this step, AliasVault will default to use public email domains offered by SpamOK. While this still works for creating aliases, it has privacy limitations. For complete privacy and control, we recommend setting up your own domain. -> [Learn more about the differences between private and public email domains](../misc/private-vs-public-email.md). +{: .note } +If you skip this step, AliasVault will default to use public email domains offered by SpamOK. While this still works for creating aliases, it has privacy limitations. For complete privacy and control, we recommend setting up your own domain. [Learn more about the differences between private and public email domains](../misc/private-vs-public-email.md). --- ### Requirements -- A **public IPv4 address** with ports 25 and 587 pointing to your AliasVault server -- Open ports **25** and **587** on your server firewall for email SMTP traffic. +- A **public IPv4 address** with ports 25 and 587 forwarded to your AliasVault server +- Open ports **25** and **587** on your server firewall for email SMTP traffic (*NOTE: some residential IP's block this, check with your ISP*). #### Verifying Port Access -While the AliasVault docker containers are running, use `telnet` to confirm your public IP allows access to the ports: +While the AliasVault docker container is running, use `telnet` to confirm your public IP allows access to the ports: ```bash # Test standard SMTP port diff --git a/docs/installation/install.sh/troubleshooting.md b/docs/installation/installer/troubleshooting.md similarity index 96% rename from docs/installation/install.sh/troubleshooting.md rename to docs/installation/installer/troubleshooting.md index 96a7a45af..91699af0d 100644 --- a/docs/installation/install.sh/troubleshooting.md +++ b/docs/installation/installer/troubleshooting.md @@ -1,7 +1,7 @@ --- layout: default title: Troubleshooting -parent: Install.sh +parent: Installer Script (multi-container) nav_order: 5 --- @@ -42,10 +42,10 @@ docker compose restart [container-name-here] --- ## 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: +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 service by running the following command: ```bash -cat logs/[container-name-here].log +cat logs/[service-name-here].txt ``` --- diff --git a/docs/installation/install.sh/update/index.md b/docs/installation/installer/update/index.md similarity index 97% rename from docs/installation/install.sh/update/index.md rename to docs/installation/installer/update/index.md index f7d8b9c3a..655de6ff8 100644 --- a/docs/installation/install.sh/update/index.md +++ b/docs/installation/installer/update/index.md @@ -1,7 +1,7 @@ --- layout: default title: Update -parent: Install.sh +parent: Installer Script (multi-container) nav_order: 3 --- diff --git a/docs/installation/install.sh/update/v0.22.0.md b/docs/installation/installer/update/v0.22.0.md similarity index 100% rename from docs/installation/install.sh/update/v0.22.0.md rename to docs/installation/installer/update/v0.22.0.md diff --git a/docs/installation/manual-setup.md b/docs/installation/manual-setup.md deleted file mode 100644 index 35399eecc..000000000 --- a/docs/installation/manual-setup.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -layout: default -title: Manual Setup -parent: Self-hosting -nav_order: 6 ---- - -# Manual Setup - -If you prefer to manually set up AliasVault instead of using the `install.sh` script, this README provides step-by-step instructions. - -**Prerequisities:** -- Docker (20.10+) and Docker Compose (2.0+) installed on your system - - See instructions: [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/) -- Knowledge of working with direct Docker commands -- Knowledge of .env files -- OpenSSL for generating random passwords - ---- - -{: .toc } -* TOC -{:toc} - ---- - - -## Steps -Follow these steps to manually install AliasVault on your own server. - -1. **Clone the git repository** - ```bash - # Clone repository - git clone https://github.com/aliasvault/aliasvault.git - - # Navigate to the AliasVault directory - cd aliasvault - ``` - -2. **Create required directories** - - Create the following directories in your project root: - ```bash - # Create required directories - mkdir -p certificates/ssl database/postgres - ``` - -3. **Create .env file** - - ```bash - # Copy the .env.example file to create a new .env file - cp .env.example .env - ``` - -4. **Set all required settings in .env** - - Open the .env file in your favorite text editor and fill in all required variables - by following the instructions inside the file. - - ```bash - # Open the .env file with your favorite editor, e.g. nano. - nano .env - ``` - -5. **Start the docker containers** - - After you are done configuring your .env file, you can start the Docker Compose stack: - ```bash - # Start the docker compose stack - docker compose up -d - ``` - -6. **Access AliasVault** - - AliasVault should now be running. You can access it at: - - - Admin Panel: https://localhost/admin - - Username: admin - - Password: [Use the password you set in the .env file] - - - Client Website: https://localhost/ - - Create your own account from here - - > Note: if you changed the default ports from 80/443 to something else in the .env file, use those ports to access AliasVault here. - -7. **Configuring private email domains** - - By default, the AliasVault private email domains feature is disabled. If you wish to enable this to use your own private domains to create email aliases with, please read the `Email Server Setup` section in the main installation guide [Basic Install](../install.md#3-email-server-setup). - - For more information, read the article explaining the differences between AliasVault's [private and public domains](../../misc/private-vs-public-email.md). - - -## Important Notes - -- Make sure to save both the admin password and PostgreSQL password in a secure location. -- Always keep your .env file secure and do not share it, as it contains sensitive information. -- The PostgreSQL data is persisted in the `database/postgres` directory. -- The docker-compose.yml file uses the `:latest` tag for containers by default. This means it always uses the latest available AliasVault version. In order to update AliasVault to a newer version at a later time, you can pull new containers when they are available with this command: -``` -docker compose pull && docker compose down && docker compose up -d -``` - -## Using a Custom Reverse Proxy (e.g. Cloudflare Tunnel) - -AliasVault includes its own internal reverse proxy (nginx) container that routes traffic to other containers. By default, the built-in nginx container (`reverse-proxy`) makes AliasVault's services available at: - -- **Client**: `http://localhost/` -- **API**: `http://localhost/api` -- **Admin**: `http://localhost/admin` - -If you want to use your own reverse proxy setup (e.g. with a Cloudflare Tunnel), you **must** ensure the following: - -- Your custom proxy/tunnel **points to the AliasVault `reverse-proxy` container**, **not** directly to the client, API, or admin containers. -- The forwarding protocol must be **HTTPS**, since the `reverse-proxy` container listens on port `443` for secure connections. - -> ⚠️ Failing to route through the reverse-proxy container correctly will break the app. Errors such as HTTP 502 often indicate a misconfigured reverse proxy. - -If you're using **Cloudflare Tunnel**, you will likely encounter TLS verification issues. In that case, go to the Cloudflare dashboard and enable the **"No TLS Verify"** option for your tunnel configuration. This tells Cloudflare to skip certificate validation when connecting to the internal reverse-proxy over HTTPS. - - -## Troubleshooting -If you encounter any miscellaneous issues during the setup: - -1. Check the Docker logs: - ```bash - docker compose logs - ``` -2. Ensure all required ports (80, 443, 25, 587 and 5432) are available and not being used by other services. -3. Verify that all variables in the .env file are set correctly. -4. Check PostgreSQL container logs specifically: - ```bash - docker compose logs postgres - ``` - -For more detailed troubleshooting information, please refer to the full [troubleshooting guide](../troubleshooting.md). - -## FAQ -### Why does AliasVault use its own reverse proxy? -AliasVault requires precise routing between its client, API, and admin interfaces. These are structured under `/`, `/api`, and `/admin`. A unified nginx reverse proxy ensures that all AliasVault's containers are accessible under the same hostname and path structure. If you use your own reverse proxy, you must replicate this logic exactly. See the [nginx.conf](https://raw.githubusercontent.com/aliasvault/aliasvault/refs/heads/main/apps/server/nginx.conf) configuration that's used by the official container for reference. diff --git a/docs/installation/manual/advanced/database.md b/docs/installation/manual/advanced/database.md new file mode 100644 index 000000000..d4f0dd357 --- /dev/null +++ b/docs/installation/manual/advanced/database.md @@ -0,0 +1,25 @@ +--- +layout: default +title: Database Operations +parent: Advanced +grand_parent: Manual Setup (single container) +nav_order: 4 +--- + +# Database Operations +This page explains how to import/export on the AliasVault server database via the `./install.sh` script. + +## Database Export +In order to backup the AliasVault server database (which includes all encrypted user vaults as well), you can use the `install.sh` script. This script will stop all services, export the database to a file, and then restart the services. + +```bash +./install.sh db-backup > backup.sql.gz +``` + +## Database Import + +To restore a previously exported database, you can use the `install.sh` script. This script will stop all services, drop the database, import the database from a file, and then restart the services. + +```bash +./install.sh db-restore < backup.sql.gz +``` diff --git a/docs/installation/manual/advanced/index.md b/docs/installation/manual/advanced/index.md new file mode 100644 index 000000000..52cf4b3a4 --- /dev/null +++ b/docs/installation/manual/advanced/index.md @@ -0,0 +1,9 @@ +--- +layout: default +title: Advanced +parent: Manual Setup (single container) +nav_order: 1 +--- + +# Advanced Installation +The following guides provide more advanced installation options for AliasVault. These options are not required for the basic installation, but may be useful for advanced users. diff --git a/docs/installation/manual/advanced/lifecycle.md b/docs/installation/manual/advanced/lifecycle.md new file mode 100644 index 000000000..18240feca --- /dev/null +++ b/docs/installation/manual/advanced/lifecycle.md @@ -0,0 +1,30 @@ +--- +layout: default +title: Stop/start +parent: Advanced +grand_parent: Manual Setup (single container) +nav_order: 2 +--- + +# Stopping and starting AliasVault +You can stop and start AliasVault via the default docker compose commands. + +## Stop +To stop AliasVault: +```bash +docker compose down +``` + +## Start +To start AliasVault: + +```bash +docker compose up -d +``` + +## Restart +To restart AliasVault: + +```bash +docker compose restart +``` diff --git a/docs/installation/install.sh/advanced/uninstall.md b/docs/installation/manual/advanced/uninstall.md similarity index 92% rename from docs/installation/install.sh/advanced/uninstall.md rename to docs/installation/manual/advanced/uninstall.md index 0b4d82cb8..4487425ff 100644 --- a/docs/installation/install.sh/advanced/uninstall.md +++ b/docs/installation/manual/advanced/uninstall.md @@ -2,6 +2,7 @@ layout: default title: Uninstall parent: Advanced +grand_parent: Manual Setup (single container) nav_order: 4 --- diff --git a/docs/installation/docker/index.md b/docs/installation/manual/index.md similarity index 82% rename from docs/installation/docker/index.md rename to docs/installation/manual/index.md index a1f941826..8b137775c 100644 --- a/docs/installation/docker/index.md +++ b/docs/installation/manual/index.md @@ -5,27 +5,24 @@ parent: Self-hosting nav_order: 2 --- -# Self-host via All-In-One Docker image +# Self-host using manual setup (single container) The following guide will walk you through the steps to install AliasVault via the All-In-One Docker container. This container uses `s6-overlay` to combine all AliasVault's services into one image for convenience. The only downside compared to the `install.sh` installer is that this version does NOT come with SSL support, so you'll have to make the container available through your own SSL proxy. -**Prerequisites:** - -This guide assumes you already have the following: -- Docker (20.10+) and Docker Compose (2.0+) installed on your system - - See instructions: [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/) -- You have existing SSL proxy infrastructure (Traefik, Nginx, HAProxy, Cloudflare Tunnel) -- Knowledge of working with direct Docker commands -- Knowledge of .yml and .env files +{: .important-title } +> Requirements: +> - Docker (20.10+) and Docker Compose (2.0+) installed on your system +> - See instructions: [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/) +> - You have existing SSL proxy infrastructure (Traefik, Nginx, HAProxy, Cloudflare Tunnel) +> - Knowledge of working with direct Docker commands +> - Knowledge of .yml and .env files ## 1. Basic installation 1. Create a new folder where you want to store AliasVault's data and configuration folders. - ```bash mkdir aliasvault cd aliasvault ``` - -2. Create a new `docker-compose.yml` file with the following contents. Note: this will auto-create the directories specified in `volumes:` in the current folder. +2. Create a new `docker-compose.yml` file with the following contents. Note: the directories specified in `volumes:` will be auto-created in the current folder on container first start. ```yaml services: @@ -51,20 +48,25 @@ services: SUPPORT_EMAIL: "" PRIVATE_EMAIL_DOMAINS: "" ``` - 3. Run `docker-compose up -d` to start the container. +4. After the container has started, AliasVault should now be running. You can access it at: -4. After the container has started, AliasVault will be accessible at: - - Client: http://localhost/ or https://localhost/ - - Admin: http://localhost/admin or https://localhost/admin - - API: http://localhost/api or https://localhost/api + - Admin Panel: http://localhost/admin + - **Username:** admin + - **Password:** [*Read instructions on page*] + + - Client Website: http://localhost/ + - Create your own account from here + + - API: http://localhost/api + - Used for configuring the browser extension and mobile app to connect to your server --- ## 2. SSL configuration HTTPS is required to use AliasVault for using: - Web app via non-localhost URLs (because of browser crypto restrictions) -- Mobile apps require the API URL to have a valid SSL certificate, otherwise the app refuses to connect +- Mobile apps require the API URL to have a valid SSL certificate, otherwise the app refuses to connect via HTTPS Configure your existing SSL infrastructure (Traefik, Nginx, HAProxy, CloudFlare Tunnel) to make the AliasVault container available through HTTPS with a valid SSL certificate. E.g. `https://aliasvault.yourdomain.com`. @@ -81,8 +83,8 @@ If you skip this step, AliasVault will default to use public email domains offer --- ### Requirements -- A **public IPv4 address** with ports 25 and 587 pointing to your AliasVault server -- Open ports **25** and **587** on your server firewall for email SMTP traffic (NOTE: some residential IP's block this, check with your ISP). +- A **public IPv4 address** with ports 25 and 587 forwarded to your AliasVault server +- Open ports **25** and **587** on your server firewall for email SMTP traffic (*NOTE: some residential IP's block this, check with your ISP*). #### Verifying Port Access diff --git a/docs/installation/manual/troubleshooting.md b/docs/installation/manual/troubleshooting.md new file mode 100644 index 000000000..ae40d65df --- /dev/null +++ b/docs/installation/manual/troubleshooting.md @@ -0,0 +1,82 @@ +--- +layout: default +title: Troubleshooting +parent: Manual Setup (single container) +nav_order: 2 +--- + +# 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. Check the Docker container running status: +```bash +docker compose ps +``` + +2. Check the Docker container logs +``` +docker compose logs +``` + +3. Try restarting the Docker container +```bash +docker compose 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 service by running the following command: + +```bash +cat logs/[service-name].txt +``` + +--- + +## Common Issues +Below are some common issues you might encounter and how to troubleshoot them. + +### 1. 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 and does not block port 25 + +Refer to the [installation guide](./index.md) for more information on how to configure your DNS records and ports. + + +### 2. Forgot AliasVault Admin Password +If you have lost your admin password, you can reset it by running the install script with the `reset-admin-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. + +1. SSH into the aliasvault container: +```bash +docker compose exec -it aliasvault /bin/bash +``` +2. Run the reset-admin-password.sh script: +```bash +./reset-admin-password.sh +``` +3. Remember the password outputted by the step above. Then quit out of the SSH session (ctrl+C) and then restart the container: +```bash +docker compose restart +``` +4. You can now login to the admin panel (/admin) with the new 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) \ No newline at end of file