From e2aafa3704dd1fec60a6244a9d82b535e52b22dd Mon Sep 17 00:00:00 2001 From: Leendert de Borst Date: Fri, 27 Jun 2025 10:50:23 +0200 Subject: [PATCH] Update docs (#963) --- .../advanced/build-from-source.md | 2 +- docs/installation/advanced/database.md | 2 +- docs/installation/advanced/index.md | 5 + docs/installation/advanced/manual-setup.md | 2 +- .../advanced/reverse-proxy-configuration.md | 141 ++++++++++++++++++ docs/installation/troubleshooting.md | 2 +- 6 files changed, 150 insertions(+), 4 deletions(-) create mode 100644 docs/installation/advanced/reverse-proxy-configuration.md diff --git a/docs/installation/advanced/build-from-source.md b/docs/installation/advanced/build-from-source.md index 199a6399d..6a4ed791e 100644 --- a/docs/installation/advanced/build-from-source.md +++ b/docs/installation/advanced/build-from-source.md @@ -2,7 +2,7 @@ layout: default title: Build from Source parent: Advanced -nav_order: 2 +nav_order: 3 --- # Build from Source diff --git a/docs/installation/advanced/database.md b/docs/installation/advanced/database.md index 3312bb1db..8f4c2b7b6 100644 --- a/docs/installation/advanced/database.md +++ b/docs/installation/advanced/database.md @@ -2,7 +2,7 @@ layout: default title: Database Backup parent: Advanced -nav_order: 3 +nav_order: 4 --- # Database Backup diff --git a/docs/installation/advanced/index.md b/docs/installation/advanced/index.md index 00cb8c8e2..99bc98940 100644 --- a/docs/installation/advanced/index.md +++ b/docs/installation/advanced/index.md @@ -7,3 +7,8 @@ nav_order: 2 # 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/advanced/manual-setup.md b/docs/installation/advanced/manual-setup.md index fdd1c290d..f5e217310 100644 --- a/docs/installation/advanced/manual-setup.md +++ b/docs/installation/advanced/manual-setup.md @@ -136,4 +136,4 @@ For more detailed troubleshooting information, please refer to the full [trouble ## 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 used by the official container for reference. +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/lanedirt/AliasVault/refs/heads/main/apps/server/nginx.conf) configuration that's used by the official container for reference. diff --git a/docs/installation/advanced/reverse-proxy-configuration.md b/docs/installation/advanced/reverse-proxy-configuration.md new file mode 100644 index 000000000..570a5e380 --- /dev/null +++ b/docs/installation/advanced/reverse-proxy-configuration.md @@ -0,0 +1,141 @@ +--- +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/troubleshooting.md b/docs/installation/troubleshooting.md index e5c421d9b..569988658 100644 --- a/docs/installation/troubleshooting.md +++ b/docs/installation/troubleshooting.md @@ -1,7 +1,7 @@ --- layout: default title: Troubleshooting -parent: Installation Guide +parent: Server Installation nav_order: 5 ---