From b603a177e2d95d7d8ae1e77ba4be75e90baf7ab3 Mon Sep 17 00:00:00 2001 From: Leendert de Borst Date: Sun, 7 Sep 2025 11:39:21 +0200 Subject: [PATCH] Add update and troubleshooting docs (#1181) --- docs/index.md | 4 +- docs/installation/installer/index.md | 2 +- .../installation/installer/troubleshooting.md | 4 +- docs/installation/installer/update/index.md | 2 +- docs/installation/installer/update/v0.22.0.md | 1 + docs/installation/manual/advanced/index.md | 2 +- .../installation/manual/advanced/lifecycle.md | 2 +- docs/installation/manual/index.md | 12 ++-- docs/installation/manual/troubleshooting.md | 6 +- docs/installation/manual/update/index.md | 66 +++++++++++++++++++ 10 files changed, 84 insertions(+), 17 deletions(-) create mode 100644 docs/installation/manual/update/index.md diff --git a/docs/index.md b/docs/index.md index 1095c4b6d..ea8a26b9a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,7 +9,7 @@ permalink: / # AliasVault Documentation {: .fs-9 } -A self-hostable, end-to-end encrypted password manager with a built-in alias generator and email server. +A privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable. {: .fs-6 .fw-300 } @@ -37,7 +37,7 @@ All data is end-to-end encrypted on the client. Your master password never leave Generate virtual email addresses for each identity. Emails sent to these addresses are instantly visible in the AliasVault app. ### Virtual Identities -Create separate identities for different purposes, each with its own email aliases and credentials. +Create separate identities for different purposes, each with its own email aliases. --- diff --git a/docs/installation/installer/index.md b/docs/installation/installer/index.md index 0342b66d3..241f3157e 100644 --- a/docs/installation/installer/index.md +++ b/docs/installation/installer/index.md @@ -43,7 +43,7 @@ chmod +x install.sh - Client: `https://localhost` - Admin: `https://localhost/admin` -> Note: if you do not wish to run the `install.sh` wizard but want to use Docker commands directly, follow the [manual setup guide](advanced/manual-setup.md). We do however encourage the use of `install.sh` as it will guide you through all configuration steps and allow you to easily update your AliasVault server later. +> Note: if you do not wish to run the `install.sh` wizard but prefer to use Docker commands directly, follow the [manual setup guide](../manual) instead. --- diff --git a/docs/installation/installer/troubleshooting.md b/docs/installation/installer/troubleshooting.md index b8ee1bf78..80ed7383f 100644 --- a/docs/installation/installer/troubleshooting.md +++ b/docs/installation/installer/troubleshooting.md @@ -98,7 +98,7 @@ If you are not receiving emails on your aliases, check the following: - Check your server's firewall settings - Verify that your ISP/hosting provider allows SMTP traffic -Refer to the [installation guide](./install.md) for more information on how to configure your DNS records and ports. +Refer to the [installation guide](./#3-email-server-setup) for more information on how to configure your DNS records and ports. ### 4. Forgot AliasVault Admin Password @@ -113,4 +113,4 @@ If you have lost your admin password, you can reset it by running the install sc ## 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 +Find all contact information on the contact page of our website: [https://www.aliasvault.net/contact](https://www.aliasvault.net/contact) \ No newline at end of file diff --git a/docs/installation/installer/update/index.md b/docs/installation/installer/update/index.md index 655de6ff8..87ed6ee45 100644 --- a/docs/installation/installer/update/index.md +++ b/docs/installation/installer/update/index.md @@ -56,5 +56,5 @@ To install a specific version and skip the automatic version checks, run the ins ./install.sh install # Example: -./install.sh install 0.7.0 +./install.sh install 0.22.0 ``` diff --git a/docs/installation/installer/update/v0.22.0.md b/docs/installation/installer/update/v0.22.0.md index ad2efbf8b..5b2118e00 100644 --- a/docs/installation/installer/update/v0.22.0.md +++ b/docs/installation/installer/update/v0.22.0.md @@ -2,6 +2,7 @@ layout: default title: Update to v0.22.0 parent: Update +grand_parent: Installer Script (multi-container) nav_order: 1 --- diff --git a/docs/installation/manual/advanced/index.md b/docs/installation/manual/advanced/index.md index 52cf4b3a4..053f671a5 100644 --- a/docs/installation/manual/advanced/index.md +++ b/docs/installation/manual/advanced/index.md @@ -2,7 +2,7 @@ layout: default title: Advanced parent: Manual Setup (single container) -nav_order: 1 +nav_order: 2 --- # Advanced Installation diff --git a/docs/installation/manual/advanced/lifecycle.md b/docs/installation/manual/advanced/lifecycle.md index 18240feca..41851e6aa 100644 --- a/docs/installation/manual/advanced/lifecycle.md +++ b/docs/installation/manual/advanced/lifecycle.md @@ -7,7 +7,7 @@ nav_order: 2 --- # Stopping and starting AliasVault -You can stop and start AliasVault via the default docker compose commands. +You can stop and start AliasVault via the default docker compose commands. Run these commands from the directory where your AliasVault `docker-compose.yml` is located. ## Stop To stop AliasVault: diff --git a/docs/installation/manual/index.md b/docs/installation/manual/index.md index 680e7f66b..0f5889cba 100644 --- a/docs/installation/manual/index.md +++ b/docs/installation/manual/index.md @@ -64,11 +64,11 @@ services: --- ## 2. SSL/TLS 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 TLS certificate, otherwise the app refuses to connect via HTTPS +To use AliasVault securely, HTTPS is required in the following situations: +- When accessing the web app from any address other than `localhost` (due to browser security restrictions) +- When using the mobile apps, which require the API URL to have a valid TLS certificate; otherwise, the app will not connect -Configure your existing TLS infrastructure (Traefik, Nginx, HAProxy, CloudFlare Tunnel) to make the AliasVault container available through HTTPS with a valid SSL/TLS certificate. E.g. `https://aliasvault.yourdomain.com`. +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`. --- @@ -160,10 +160,10 @@ This keeps the email configuration of your primary domain (`example.com`) comple After setting up your DNS, you have to configure AliasVault to let it know which email domains it should support. Update the `docker-compose.yml` file: ```bash -[..] - +# ... environment: PRIVATE_EMAIL_DOMAINS: "yourdomain1.com,yourdomain2.com" +# ... ``` After updating the docker-compose.yml file, issue a `docker compose restart`. Afterwards, when you login to the AliasVault web app, you should now be able to create an alias with your domain and be able to receive email on it. diff --git a/docs/installation/manual/troubleshooting.md b/docs/installation/manual/troubleshooting.md index ae40d65df..d94d90914 100644 --- a/docs/installation/manual/troubleshooting.md +++ b/docs/installation/manual/troubleshooting.md @@ -2,7 +2,7 @@ layout: default title: Troubleshooting parent: Manual Setup (single container) -nav_order: 2 +nav_order: 3 --- # Troubleshooting @@ -54,7 +54,7 @@ If you are not receiving emails on your aliases, check the following: - 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. +Refer to the [installation guide](./#3-email-server-setup) for more information on how to configure your DNS records and ports. ### 2. Forgot AliasVault Admin Password @@ -79,4 +79,4 @@ docker compose restart ## 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 +Find all contact information on the contact page of our website: [https://www.aliasvault.net/contact](https://www.aliasvault.net/contact) \ No newline at end of file diff --git a/docs/installation/manual/update/index.md b/docs/installation/manual/update/index.md new file mode 100644 index 000000000..4e459b7a4 --- /dev/null +++ b/docs/installation/manual/update/index.md @@ -0,0 +1,66 @@ +--- +layout: default +title: Update +parent: Manual Setup (single container) +nav_order: 1 +--- + +# Updating AliasVault +{: .no_toc } + +
+ + Table of contents + + {: .text-delta } +1. TOC +{:toc} +
+ +## Before You Begin +You can see the latest available version of AliasVault on [GitHub](https://github.com/aliasvault/aliasvault/releases). + +{: .warning } +Before updating, it's recommended to backup your database and other important data. You can do this by making +a copy of the `database` and `certificates` directories. + +## Standard Update Process +For most version updates, you can use the standard update process. The container will automatically handle database migrations on startup: + +1. Navigate to your AliasVault directory: +```bash +cd /path/to/your/aliasvault +``` + +2. Pull the latest Docker image: +```bash +docker compose pull +``` + +3. Restart the container with the new image: +```bash +docker compose down && docker compose up -d +``` + +## Version-Specific Upgrade Guides +While database migrations are automated, some releases may require manual file/config migration steps. Always check this page before updating to ensure you don't miss any required manual steps. + +> Currently there are no version-specific manual migration steps required for the single container setup. Check back here when updating to ensure you haven't missed any new requirements. + +## Additional Update Options + +### Installing a Specific Version +If you need to install a specific version instead of the latest, you can do the following. Note: downgrading to a previous version is not officially supported and may lead to unexpected issues, as database schema changes may prevent older versions from working correctly. + +1. Edit your `docker-compose.yml` file +2. Change the image tag from `:latest` to a specific version: +```yaml +# ... +image: ghcr.io/aliasvault/aliasvault:0.23.0 # Replace with desired version +# ... rest of configuration +``` +3. Pull and restart: +```bash +docker compose pull +docker compose down && docker compose up -d +```