mirror of
https://github.com/lanedirt/AliasVault.git
synced 2025-12-05 19:07:26 -06:00
Add advanced and troubleshooting steps per self-host method (#1181)
This commit is contained in:
Leendert de Borst
2
.vscode/tasks.json
vendored
2
.vscode/tasks.json
vendored
@@ -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",
|
||||
|
||||
@@ -38,3 +38,6 @@ callouts:
|
||||
note:
|
||||
title: Note
|
||||
color: purple
|
||||
important:
|
||||
title: Important
|
||||
color: yellow
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
@@ -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).
|
||||
@@ -2,6 +2,7 @@
|
||||
layout: default
|
||||
title: Build from Source
|
||||
parent: Advanced
|
||||
grand_parent: Installer Script (multi-container)
|
||||
nav_order: 3
|
||||
---
|
||||
|
||||
25
docs/installation/installer/advanced/database.md
Normal file
25
docs/installation/installer/advanced/database.md
Normal file
@@ -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
|
||||
```
|
||||
9
docs/installation/installer/advanced/index.md
Normal file
9
docs/installation/installer/advanced/index.md
Normal file
@@ -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.
|
||||
@@ -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.
|
||||
20
docs/installation/installer/advanced/uninstall.md
Normal file
20
docs/installation/installer/advanced/uninstall.md
Normal file
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
@@ -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
|
||||
```
|
||||
|
||||
---
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: default
|
||||
title: Update
|
||||
parent: Install.sh
|
||||
parent: Installer Script (multi-container)
|
||||
nav_order: 3
|
||||
---
|
||||
|
||||
@@ -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.
|
||||
25
docs/installation/manual/advanced/database.md
Normal file
25
docs/installation/manual/advanced/database.md
Normal file
@@ -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
|
||||
```
|
||||
9
docs/installation/manual/advanced/index.md
Normal file
9
docs/installation/manual/advanced/index.md
Normal file
@@ -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.
|
||||
30
docs/installation/manual/advanced/lifecycle.md
Normal file
30
docs/installation/manual/advanced/lifecycle.md
Normal file
@@ -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
|
||||
```
|
||||
@@ -2,6 +2,7 @@
|
||||
layout: default
|
||||
title: Uninstall
|
||||
parent: Advanced
|
||||
grand_parent: Manual Setup (single container)
|
||||
nav_order: 4
|
||||
---
|
||||
|
||||
@@ -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
|
||||
|
||||
82
docs/installation/manual/troubleshooting.md
Normal file
82
docs/installation/manual/troubleshooting.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user