From 82b2b7512782df8a9ce72f9e82f221d44b7564fa Mon Sep 17 00:00:00 2001 From: Leendert de Borst Date: Wed, 25 Dec 2024 14:24:31 +0100 Subject: [PATCH] Update docs with new update instructions (#190) --- docs/installation/advanced/manual-setup.md | 39 +++++++++++++----- .../{update.md => update/index.md} | 29 +++++++++++--- docs/installation/update/v0.10.0.md | 40 +++++++++++++++++++ 3 files changed, 92 insertions(+), 16 deletions(-) rename docs/installation/{update.md => update/index.md} (64%) create mode 100644 docs/installation/update/v0.10.0.md diff --git a/docs/installation/advanced/manual-setup.md b/docs/installation/advanced/manual-setup.md index a29168ab1..80e294f4a 100644 --- a/docs/installation/advanced/manual-setup.md +++ b/docs/installation/advanced/manual-setup.md @@ -20,7 +20,7 @@ If you prefer to manually set up AliasVault, this README provides step-by-step i Create the following directories in your project root: ```bash - mkdir -p certificates/ssl certificates/app database logs/msbuild + mkdir -p certificates/ssl certificates/app database/postgres ``` 2. **Create .env file** @@ -61,7 +61,21 @@ If you prefer to manually set up AliasVault, this README provides step-by-step i DATA_PROTECTION_CERT_PASS=your_generated_password_here ``` -6. **Set PRIVATE_EMAIL_DOMAINS** +6. **Configure PostgreSQL Settings** + + Set the following PostgreSQL-related variables in your .env file: + ```bash + # Database name (default: aliasvault) + POSTGRES_DB=aliasvault + + # Database user (default: aliasvault) + POSTGRES_USER=aliasvault + + # Generate a secure password for PostgreSQL + POSTGRES_PASSWORD=$(openssl rand -base64 32) + ``` + +7. **Set PRIVATE_EMAIL_DOMAINS** Update the .env file with allowed email domains. Use DISABLED.TLD to disable email support: ```bash @@ -72,14 +86,14 @@ If you prefer to manually set up AliasVault, this README provides step-by-step i PRIVATE_EMAIL_DOMAINS=DISABLED.TLD ``` -7. **Set SUPPORT_EMAIL (Optional)** +8. **Set SUPPORT_EMAIL (Optional)** Add a support email address if desired: ```bash SUPPORT_EMAIL=support@yourdomain.com ``` -8. **Generate admin password** +9. **Generate admin password** Build the Docker image for password hashing: ```bash @@ -97,7 +111,7 @@ If you prefer to manually set up AliasVault, this README provides step-by-step i ADMIN_PASSWORD_GENERATED=2024-01-01T00:00:00Z ``` -9. **Build and start Docker containers** +10. **Build and start Docker containers** Build the Docker Compose stack: ```bash @@ -109,22 +123,23 @@ If you prefer to manually set up AliasVault, this README provides step-by-step i docker compose up -d ``` -10. **Access AliasVault** +11. **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 step 8] + - Password: [Use the password you set in step 9] - Client Website: https://localhost/ - Create your own account from here ## Important Notes -- Make sure to save the admin password you used in step 8 in a secure location. -- If you need to reset the admin password in the future, repeat step 8 and restart the Docker containers. +- Make sure to save both the admin password and PostgreSQL password in a secure location. +- If you need to reset the admin password in the future, repeat step 9 and restart the Docker containers. - 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. ## Troubleshooting @@ -134,7 +149,11 @@ If you encounter any issues during the setup: ```bash docker compose logs ``` -2. Ensure all required ports (80 and 443) are available and not being used by other services. +2. Ensure all required ports (80, 443, and 5432) are available and not being used by other services. 3. Verify that all environment variables in the .env file are set correctly. +4. Check PostgreSQL container logs specifically: + ```bash + docker compose logs postgres + ``` For further assistance, please refer to the project documentation or seek support through the appropriate channels. diff --git a/docs/installation/update.md b/docs/installation/update/index.md similarity index 64% rename from docs/installation/update.md rename to docs/installation/update/index.md index d4737bc1e..e261771d5 100644 --- a/docs/installation/update.md +++ b/docs/installation/update/index.md @@ -6,16 +6,26 @@ nav_order: 3 --- # Updating AliasVault -To update AliasVault to the latest version, run the install script with the `update` option. This will pull the latest version of AliasVault from GitHub and restart all containers. +{: .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/lanedirt/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. -## Updating to the latest available version -To update to the latest version, run the install script with the `update` option. The script will check for the latest version and prompt you to confirm the update. Follow the prompts to complete the update. +## Standard Update Process +For most version updates, you can use the standard update process: ```bash ./install.sh update @@ -23,7 +33,14 @@ To update to the latest version, run the install script with the `update` option > Tip: to skip the confirmation prompts and automatically proceed with the update, use the `-y` flag: `./install.sh update -y` -## Updating the installer script +## Version-Specific Upgrade Guides +Some versions require additional steps during upgrade. If you are upgrading from an older version, please check the relevant upgrade guide below: + +- [Updating to v0.10.0](v0-10-0.html) - SQLite to PostgreSQL migration + +## Additional Update Options + +### Updating the installer script The installer script can check for and apply updates to itself. This is done as part of the `update` command. However you can also update the installer script separately with the `update-installer` command. This is useful if you want to update the installer script without updating AliasVault itself, e.g. as a separate step during CI/CD pipeline. ```bash @@ -32,8 +49,8 @@ The installer script can check for and apply updates to itself. This is done as > Tip: to skip the confirmation prompts and automatically proceed with the update, use the `-y` flag: `./install.sh update-installer -y` -## Installing a specific version -To install a specific version and skip the automatic version checks, run the install script with the `install` option and specify the version you want to install. +### Installing a specific version +To install a specific version and skip the automatic version checks, run the install script with the `install` option and specify the version you want to install. Note that downgrading is not supported officially and may lead to unexpected issues. ```bash ./install.sh install diff --git a/docs/installation/update/v0.10.0.md b/docs/installation/update/v0.10.0.md new file mode 100644 index 000000000..8fbcbbe36 --- /dev/null +++ b/docs/installation/update/v0.10.0.md @@ -0,0 +1,40 @@ +--- +layout: default +title: Update to v0.10.0 +parent: Update +grand_parent: Installation Guide +nav_order: 1 +--- + +# Upgrading to v0.10.0 +{: .no_toc } + +This guide covers the upgrade process from version < v0.10.0 to v0.10.0 or newer, which includes a one-time database migration from SQLite to PostgreSQL. + +The v0.10.0 release introduces a new database backend, PostgreSQL, which replaces SQLite. This change is required because SQLite is not suitable for environments with concurrent writes that AliasVault requires. + +A built-in database migration tool is included in the installer script to help you migrate your data from SQLite to PostgreSQL. + +## Update Steps + +1. First, backup your existing SQLite database: +```bash +cp database/AliasServerDb.sqlite database/AliasServerDb.sqlite.backup +``` +2. Update AliasVault to the latest version: +```bash +./install.sh update +``` +3. Run the database migration tool: +```bash +./install.sh migrate-db +``` + +4. If the migration has completed successfully, restart AliasVault: +```bash +./install.sh restart +``` + +5. Test the upgrade by logging in to the admin panel and checking that your data is intact. + +If you encounter any issues during the upgrade, please create an issue on the [GitHub repository](https://github.com/lanedirt/AliasVault/issues) or contact via Discord.