mirror/aliasvault
1
0
Fork 0
mirror of https://github.com/aliasvault/aliasvault.git synced 2026-02-07 04:43:00 -05:00
Code Issues Packages Projects Releases Wiki Activity

Update isntall docs and troubleshooting steps

Browse Source
This commit is contained in:
Leendert de Borst
2026-02-04 21:37:45 +01:00
parent baa57623b7
commit fd888728d4
4 changed files with 155 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/_config.yml
View File

@@ -54,3 +54,8 @@ url: "https://docs.aliasvault.net"
plugins:
- jekyll-sitemap
- jekyll-redirect-from
markdown: kramdown
kramdown:
toc_levels: [2, 3]

26
docs/installation/docker-compose/index.md
View File

@@ -11,6 +11,15 @@ nav_order: 2
# Self-host using Docker Compose (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/TLS support, so you'll have to make the container available through your own SSL/TLS proxy.
<details open markdown="block">
<summary>
Table of contents
</summary>
{: .text-delta }
1. TOC
{:toc}
</details>
{: .important-title }
> Requirements:
> - Docker (20.10+) and Docker Compose (2.0+) installed on your system
@@ -77,18 +86,6 @@ To use AliasVault securely, HTTPS is required in the following situations:
You must set up and configure your own TLS/SSL infrastructure (such as Traefik, Nginx, HAProxy, or Cloudflare Tunnel) to make the AliasVault container accessible over HTTPS with a valid SSL/TLS certificate. For example: `https://aliasvault.yourdomain.com`.
### Troubleshooting
#### Enabling WebSockets
If you're accessing the Admin page through a reverse proxy and encounter errors after login, check that the Upgrade header is allowed and forwarded. This is required because the Admin app is built with .NET Blazor Server, which uses WebSockets for client-server communication. For example, when using nginx:
```nginx
# Add WebSocket support for Blazor server
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 86400;
```
---
## 3. Email Server Setup
@@ -191,3 +188,8 @@ Afterwards, when you login to the AliasVault web app, you should now be able to
Important: DNS propagation can take up to 24-48 hours. During this time, email delivery might be inconsistent.
If you encounter any issues, feel free to join the [Discord chat](https://discord.gg/DsaXMTEtpF) to get help from other users and maintainers.
---
## 4. Troubleshooting
For more detailed troubleshooting information, please refer to the [troubleshooting guide](./troubleshooting.md).

178
docs/installation/docker-compose/troubleshooting.md
View File

@@ -15,79 +15,155 @@ This guide covers common issues and troubleshooting steps for AliasVault encount
---
## 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](./#3-email-server-setup) for more information on how to configure your DNS records and ports.
### 2. Admin app not working via your own reverse proxy
If you're accessing the Admin page through your own reverse proxy and encounter errors after login, check that the Upgrade header is allowed and forwarded. This is required because the Admin app is built with .NET Blazor Server, which uses WebSockets for client-server communication. For example, when using nginx:
```nginx
# Add WebSocket support for Blazor server
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 86400;
```
### 3. Forgot AliasVault admin password
If you have lost your admin password, you can reset it by running the `aliasvault reset-admin-password` option. This will generate a new random password and update the secret. 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
$ aliasvault reset-admin-password
```
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.
---
## 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:
For any issues you might encounter, the first step is to check the Docker container health. This will give you a quick insight into the status of the container which will help you identify the root cause of the issue.
**1. Check the Docker container running status:**
```bash
$ docker compose ps
docker compose ps
```
2. Check the Docker container logs
**2. Check the Docker container logs:**
```bash
$ docker compose logs
docker compose logs
```
3. Try restarting the Docker container
**3. Try restarting the Docker container:**
```bash
$ docker compose restart
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:
All AliasVault services log information and errors to text files. These files are located in the `logs` directory within your AliasVault installation folder.
**View logs for a specific service:**
```bash
$ cat logs/[service-name].txt
cat logs/[service-name].txt
```
**View PostgreSQL logs:**
```bash
cat logs/postgres/postgres.log
```
If PostgreSQL failed during initialization, also check:
```bash
cat logs/postgres/initdb.log
```
---
## Common Issues
Below are some common issues you might encounter and how to troubleshoot them.
### 1. PostgreSQL fails to start
**Symptoms:**
- Container fails to start or keeps restarting
- Error messages about database connection failures
- Services unable to connect to the database
**Steps:**
1. Check the PostgreSQL logs for error details:
```bash
cat logs/postgres/postgres.log
```
2. If PostgreSQL failed during initialization, check the init logs:
```bash
cat logs/postgres/initdb.log
```
3. **Permission errors:** If you see permission-related errors, ensure the `database` folder has correct permissions for the user running the Docker container.
4. **Corrupted database:** If the database appears corrupted, you may need to reinitialize it. **Warning:** This will delete all data:
```bash
# Stop containers first
docker compose down
# Remove the postgres data directory
sudo rm -rf database/postgres/
# Restart containers (will reinitialize the database)
docker compose up -d
```
### 2. No emails being received
**Symptoms:**
- Aliases not receiving any emails
- Emails to aliases bounce or timeout
**Steps:**
1. Verify DNS records are correctly configured
2. Ensure ports 25 and 587 are accessible from the internet
3. Check your server's firewall settings
4. Verify that your ISP/hosting provider allows SMTP traffic and does not block port 25
Refer to the [installation guide](./#3-email-server-setup) for more information on how to configure your DNS records and ports.
### 3. Admin app not working via your own reverse proxy
**Symptoms:**
- Errors after logging into the Admin panel
- Page loads but becomes unresponsive
- WebSocket connection errors in browser console
**Solution:**
If you're accessing the Admin page through your own reverse proxy, ensure the Upgrade header is allowed and forwarded. This is required because the Admin app uses WebSockets for client-server communication.
For nginx, add the following to your configuration:
```nginx
# Add WebSocket support for Blazor server
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 86400;
```
### 4. Forgot AliasVault admin password
**Solution:**
You can reset the admin password by running the `aliasvault reset-admin-password` command. This will generate a new random password and update the secret.
1. SSH into the aliasvault container:
```bash
docker compose exec -it aliasvault /bin/bash
```
2. Run the reset-admin-password script:
```bash
aliasvault reset-admin-password
```
3. Note the password displayed, then exit the SSH session (`Ctrl+C` or type `exit`) and restart the container:
```bash
docker compose restart
```
4. You can now log in 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://www.aliasvault.net/contact](https://www.aliasvault.net/contact)

9
docs/installation/script/index.md
View File

@@ -11,6 +11,15 @@ nav_order: 1
# Self-host using Install 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`. This script will pull pre-built Docker Images and do all the configuration for you while using `docker compose` in the background.
<details open markdown="block">
<summary>
Table of contents
</summary>
{: .text-delta }
1. TOC
{:toc}
</details>
{: .important-title }
> Requirements:
> - 64-bit Linux VM with root access (Ubuntu or RHEL-based recommended)