AliasVault 0.31.1 on AWS User Guide

Overview

This guide covers launching and verifying AliasVault 0.31.1 on Ubuntu 24.04 from cloudimg on Amazon EC2. It is one version of the cloudimg Hardened Authentik, Vaultwarden & Identity, Secrets and PKI AMIs listing on AWS Marketplace; you pick it as the software version when you subscribe and launch. The other identity, secrets and PKI products in the listing are described on the listing's guide hub.

AliasVault is an open-source (AGPL-3.0) password manager with a built-in private email-alias service. For every website you sign up to, it can generate a unique identity and email alias, receive the mail for that alias on your own server, and store the login in an end-to-end encrypted vault. Your master password never leaves your browser or app: the server stores only encrypted data, so even the server's administrator cannot read a vault. You use it from the web vault, the browser extensions and the iOS and Android apps.

Version 0.31.1 includes the fix for GHSA-7hm6-fj4m-pf6f (server-side request forgery through DNS rebinding in the favicon fetcher, fixed in 0.30.3), the 0.31.0 vault format with hardened key derivation, and admin-created invite links for servers with closed registration.

What is on the image:

• AliasVault 0.31.1, the official upstream container images (ghcr.io/aliasvault/postgres, client, api, admin, smtp and task-runner), each pinned by digest
• PostgreSQL 16 inside the AliasVault postgres image, created empty on your instance's first boot
• Docker CE (official Docker apt repository) running the six containers under one systemd unit, aliasvault.service
• nginx in front of the web vault, the API and the admin panel: HTTPS on port 443 with a self-signed certificate created on first boot
• The AliasVault mail server on port 25, with STARTTLS using the same per-instance certificate
• A per-instance admin password, JWT signing key and database password, generated on first boot into root-only files
• aliasvault-set-hostname and aliasvault-reset-admin-password, helpers for your own DNS name and a new admin password

Default user: ubuntu · Architecture: x86_64 · Root volume: 16 GiB gp3

Security posture

• No default login. The admin password (24 characters), the JWT signing key, the data-protection password, the PostgreSQL password and the abuse-metrics salt are generated on each instance's first boot. None is in the image, so no two instances share one. The admin password is stored only as a PBKDF2-HMAC-SHA512 hash for AliasVault; the plain value is in /root/aliasvault-credentials.txt (mode 0600) for you.
• Registration is closed. Nobody can create a vault account on your server from the internet. You create your own account, and anyone else's, from a single-use invite link made in the admin panel. You can open registration later if you want a public service.
• Fails closed. AliasVault will not start unless every secret exists, is long enough, is not a published default and is readable only by root. nginx stays closed until first boot has proved that the admin password works and that a wrong one is refused.
• Secrets never on a command line or in a container environment. Each container mounts only the secret files it reads (the API its JWT key, the admin panel the admin password hash, every service the database password), and docker inspect shows none of them. The admin password is hashed by a script that reads it from a root-only file; AliasVault's own reset script would put it on a command line, so the image ships aliasvault-reset-admin-password instead.
• Only nginx and the mail server face the network. The web vault, API and admin panel listen on 127.0.0.1 only, and PostgreSQL has no host port at all. nginx answers only for the configured hostname (any other Host header gets its connection closed), uses TLS 1.2 or 1.3, and replaces any client-supplied X-Forwarded-For, X-Real-IP, Forwarded or X-Forwarded-Host header, so AliasVault logs the real client address and builds invite links from the configured name. Port 80 is not used.
• The admin panel. It needs the per-instance password; nginx rate-limits the sign-in form, ASP.NET locks the admin account for 30 minutes after 10 wrong passwords, cross-origin POST requests and WebSocket upgrades are refused (403), CORS headers are stripped, and the session cookie is Secure, HttpOnly and SameSite=Lax. You can also limit it to your own networks (Step 9).
• The containers cannot read instance metadata. The API fetches website icons from addresses users enter, so every container is blocked from the instance metadata service (169.254.169.254 and fd00:ec2::254) by a Docker DOCKER-USER firewall rule that is in place before any container starts. nginx, Docker and the AliasVault units are blocked by systemd IPAddressDeny. This was proved at build time from inside each container, while the same containers could reach the internet.
• Least-privilege containers. Every container drops all Linux capabilities (the web client keeps only the three its own nginx needs to switch user) and runs with no-new-privileges; PostgreSQL runs as its own unprivileged user.
• IMDSv2 required. The AMI is registered with ImdsSupport v2.0, so instances refuse token-less (IMDSv1) metadata requests.
• Per-instance identity. SSH host keys, the machine ID, the TLS certificate, the database and Docker's engine ID are created fresh on every instance.

Prerequisites

1. An AWS account and permission to launch EC2 instances
2. An EC2 key pair in the Region you launch in
3. For email aliases: a domain whose DNS you control, and inbound TCP 25 allowed to the instance

Recommended instance type: m5.large. The six containers use about 450 MiB of memory at idle and are each capped, so the image also runs on 4 GiB instances such as t3.medium for a small team.

Connecting to your instance

Step 1: Launch the instance

Option A: AWS Marketplace console

1. Open the cloudimg Hardened Authentik, Vaultwarden & Identity, Secrets and PKI AMIs listing on AWS Marketplace and choose View purchase options, then Subscribe. One subscription covers every version in the listing.
2. Once the subscription is active, choose Launch your software.
3. Choose One-click launch from AWS Marketplace (or Launch from EC2 Console for the full launch wizard). In Version, choose AliasVault 0.31.1 on Ubuntu 24.04, then choose your Region.
4. Pick an instance type (m5.large recommended; the software charge is $0.04 per vCPU per hour) and your key pair.
5. Security group: the listing's default group opens SSH (22), HTTPS (443) and SMTP (25). Restrict SSH to your own IP address. Keep 443 open to wherever you and your apps will connect from. Keep 25 open to the internet only if you use email aliases, because other mail servers deliver to it; otherwise remove it.
6. Choose your VPC and subnet, leave the metadata defaults (the image already requires IMDSv2), then choose Launch.

Option B: AWS CLI

Run this on your own workstation. It creates a security group for SSH from your management address, HTTPS from your team's network and SMTP from anywhere, then launches the instance. Replace the AMI ID with the one shown for your Region on the Marketplace launch page, and the VPC, subnet, key pair and CIDR ranges with your own:

SG=$(aws ec2 create-security-group --group-name aliasvault \
  --description "AliasVault password manager" --vpc-id vpc-0123456789abcdef0 \
  --query GroupId --output text)
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 22 --cidr <your-mgmt-cidr>
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 443 --cidr 203.0.113.0/24
aws ec2 authorize-security-group-ingress --group-id "$SG" --protocol tcp --port 25 --cidr 0.0.0.0/0
aws ec2 run-instances \
  --image-id ami-0123456789abcdef0 \
  --instance-type m5.large \
  --key-name my-key-pair \
  --security-group-ids "$SG" \
  --subnet-id subnet-0123456789abcdef0 \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=aliasvault}]'

You do not need --metadata-options: the AMI already makes IMDSv2 required. If you use email aliases or your own DNS name, associate an Elastic IP so the address survives a stop and start.

Step 2: Connect and find your admin login

Connect as ubuntu with the key pair you chose:

ssh -i ~/.ssh/my-key-pair.pem ubuntu@<public-ip>

First boot finishes within a minute or two of launch. It sets the hostname AliasVault is served as (the instance's public DNS name when it has one), creates the TLS certificate for it, generates the secrets, creates an empty database, starts the six containers, proves the admin login works, and writes /root/aliasvault-credentials.txt (mode 0600, root). Only then does it open nginx. These are the entries in that file (the password is not shown here):

sudo grep -E '^ALIASVAULT_(URL|ADMIN_URL|ADMIN_USERNAME)=' /root/aliasvault-credentials.txt
sudo grep -oE '^[A-Z_]+=' /root/aliasvault-credentials.txt
sudo stat -c '%a %U:%G' /root/aliasvault-credentials.txt

ALIASVAULT_URL=https://ec2-44-207-6-221.compute-1.amazonaws.com/
ALIASVAULT_ADMIN_URL=https://ec2-44-207-6-221.compute-1.amazonaws.com/admin/
ALIASVAULT_ADMIN_USERNAME=admin
ALIASVAULT_URL=
ALIASVAULT_ADMIN_URL=
ALIASVAULT_ADMIN_USERNAME=
ALIASVAULT_ADMIN_PASSWORD=
600 root:root

To read the password, run sudo cat /root/aliasvault-credentials.txt in your own session and store it in a password manager. The admin password opens the admin panel only; it is not a vault account.

Step 3: Confirm AliasVault is running

Docker, the metadata firewall rule, the first-boot units, AliasVault and nginx are active. Only sshd, nginx (443) and the mail server (25) listen beyond loopback: the web vault, API and admin panel are on 127.0.0.1:3000 to 3002, and PostgreSQL's port is open only inside the private container network.

systemctl is-active docker.service cloudimg-docker-imds-deny.service aliasvault-firstboot.service aliasvault.service aliasvault-postboot.service nginx.service
sudo docker ps --format '{{.Names}} {{.Ports}}' | sort
sudo ss -Htlnp | awk '{print $4, $6}' | sed -E 's/,pid=[0-9]+,fd=[0-9]+//g' | sort -u
curl -sk https://127.0.0.1/api/; echo

active
active
active
active
active
active
aliasvault-admin 127.0.0.1:3002->3002/tcp
aliasvault-api 127.0.0.1:3001->3001/tcp
aliasvault-client 80/tcp, 127.0.0.1:3000->3000/tcp
aliasvault-postgres 5432/tcp
aliasvault-smtp 0.0.0.0:25->25/tcp, [::]:25->25/tcp
aliasvault-task-runner 
0.0.0.0:22 users:(("sshd"),("systemd"))
0.0.0.0:25 users:(("docker-proxy"))
0.0.0.0:443 users:(("nginx"),("nginx"),("nginx"))
127.0.0.1:3000 users:(("docker-proxy"))
127.0.0.1:3001 users:(("docker-proxy"))
127.0.0.1:3002 users:(("docker-proxy"))
127.0.0.53%lo:53 users:(("systemd-resolve"))
127.0.0.54:53 users:(("systemd-resolve"))
[::]:22 users:(("sshd"),("systemd"))
[::]:25 users:(("docker-proxy"))
[::]:443 users:(("nginx"),("nginx"),("nginx"))
OK

/api/ answers OK only when the API can reach its database, so it makes a good load balancer health check.

Step 4: Prove the login and the web defaults

A signed-out visit to the admin panel is sent to its sign-in page, a cross-origin POST is refused, an unknown Host header gets no answer, nothing listens on plain HTTP, and the API refuses to register an account without an invite. The last command runs the image's own end-to-end check: it creates a registration invite in the database, reads it back through the API and deletes it, and proves that default and wrong admin passwords get no session while this instance's password does:

H=$(sudo sed -n 's/^set \$app_host "\(.*\)";$/\1/p' /etc/nginx/aliasvault-host.conf)
R=(--connect-to "$H:443:127.0.0.1:443")
curl -sk "${R[@]}" -o /dev/null -w 'admin panel, signed out -> %{http_code} %{redirect_url}\n' "https://$H/admin/"
curl -sk "${R[@]}" -o /dev/null -w 'cross-origin POST to the admin login -> %{http_code}\n' -X POST -H 'Origin: https://evil.example' --data 'x=1' "https://$H/admin/user/login"
curl -sk -o /dev/null -w 'unknown Host -> %{http_code}\n' -H 'Host: evil.example' https://127.0.0.1/ || true
curl -s -o /dev/null -w 'plain http on port 80 -> %{http_code}\n' http://127.0.0.1/ || true
curl -sk "${R[@]}" -H 'Content-Type: application/json' -d '{"username":"newuser"}' "https://$H/api/v2/Auth/validate-username" | jq -c '{statusCode, code}'
sudo /usr/local/sbin/aliasvault-roundtrip.sh

admin panel, signed out -> 302 https://ec2-44-207-6-221.compute-1.amazonaws.com/admin/user/login?ReturnUrl=%2Fadmin%2F
cross-origin POST to the admin login -> 403
unknown Host -> 000
plain http on port 80 -> 000
{"statusCode":400,"code":"PUBLIC_REGISTRATION_DISABLED"}
OK round-trip https://ec2-44-207-6-221.compute-1.amazonaws.com/: web vault + API OK; unknown Host refused; registration closed; invite create->readback->delete OK; anonymous admin -> login; default/weak/wrong admin passwords refused; per-VM admin session Secure HttpOnly SameSite=Lax opens the panel

Step 5: Sign in to the admin panel

Browse to ALIASVAULT_ADMIN_URL (https://<public-dns-name>/admin/). The certificate is self-signed, so your browser warns once; accept it for this host, or install your own certificate (Step 8). A default or guessed password is refused:

Sign in with admin and ALIASVAULT_ADMIN_PASSWORD. The dashboard shows recent users, the status of the mail server and the task runner, registrations and email statistics. Turn on two-factor authentication for the admin account in Account Settings, as the banner suggests:

Step 6: Create your vault account from an invite

Because registration is closed, every vault account starts with an invite. In the admin panel choose Users, then + Invite, set how many accounts the link may create and for how many days it is valid, and choose Create invite. The link uses the configured hostname:

Open the link (or send it to the person you are inviting). The web vault asks for a username, then a master password. The master password encrypts the vault in your browser and is never sent to the server, so nobody, including the admin, can reset it for you: keep it safe.

After Create Account the vault opens, empty and ready for your first login or an import from KeePass, Bitwarden, Chrome or Firefox:

The new account is in the database, and the invite has been used up:

sudo docker exec aliasvault-postgres psql -U aliasvault -d aliasvault -tAc 'SELECT "UserName" FROM "AliasVaultUsers"'
sudo docker exec aliasvault-postgres psql -U aliasvault -d aliasvault -tAc 'SELECT "UseCount", "MaxUses" FROM "RegistrationInvites" ORDER BY "CreatedAt" DESC LIMIT 1'

demouser
1|1

To use the vault from the browser extensions or the iOS and Android apps, choose Self-hosted in the app and enter ALIASVAULT_URL. Apps check the certificate, so for them install a certificate your devices trust first (Step 8).

Step 7: Receive mail for your aliases

AliasVault's mail server listens on port 25 and accepts mail only for the domains you list. With no domain set, it accepts nothing. It offers STARTTLS with this instance's certificate and announces the configured hostname:

H=$(sudo sed -n 's/^set \$app_host "\(.*\)";$/\1/p' /etc/nginx/aliasvault-host.conf)
timeout 10 bash -c 'exec 3<>/dev/tcp/127.0.0.1/25; head -n1 <&3; printf "QUIT\r\n" >&3'
openssl s_client -starttls smtp -connect 127.0.0.1:25 -servername "$H" </dev/null 2>/dev/null | openssl x509 -noout -subject
sudo grep -E '^(PRIVATE_EMAIL_DOMAINS|SMTP_ADVERTISED_HOSTNAME|SMTP_TLS_ENABLED|PUBLIC_REGISTRATION_ENABLED)=' /opt/aliasvault/.env

220 ec2-44-207-6-221.compute-1.amazonaws.com v11.1.0.0 ESMTP ready
subject=CN = ec2-44-207-6-221.compute-1.amazonaws.com, O = cloudimg
PRIVATE_EMAIL_DOMAINS=
SMTP_ADVERTISED_HOSTNAME=ec2-44-207-6-221.compute-1.amazonaws.com
SMTP_TLS_ENABLED=true
PUBLIC_REGISTRATION_ENABLED=false

To receive mail for alias.example.com:

1. Give the instance an Elastic IP and a DNS name, for example mail.example.com, and set it with aliasvault-set-hostname (Step 8).
2. Create an MX record for alias.example.com pointing at mail.example.com.
3. Add the domain to /opt/aliasvault/.env and restart AliasVault:

sudo sed -i 's/^PRIVATE_EMAIL_DOMAINS=.*/PRIVATE_EMAIL_DOMAINS=alias.example.com/' /opt/aliasvault/.env
sudo systemctl restart aliasvault

New aliases can then use @alias.example.com, and mail sent to them appears under Emails in the vault. Mail is stored encrypted with the receiving user's key. AWS accepts inbound mail on port 25 without any request; AliasVault never sends mail, so the outbound port 25 limit does not affect it.

Step 8: Use your own DNS name and certificate

Point a DNS record at the instance (an Elastic IP keeps the address stable), then tell AliasVault the name. The helper re-issues the self-signed certificate for it (for HTTPS and STARTTLS), updates nginx's accepted names and the admin panel's cross-origin guard, sets the mail server's name, records the name in /etc/cloudimg/aliasvault-hostname (kept across reboots) and updates the credentials file:

sudo aliasvault-set-hostname vault.example.com

aliasvault-set-hostname: AliasVault is served at https://vault.example.com/

Until you set a name, the instance follows its own public DNS name: if it comes back from a stop and start with a new address, the certificate and names are updated at boot.

The mobile apps and browser extensions need a certificate they trust. To use one from your own CA or from Let's Encrypt, set the name with aliasvault-set-hostname first (so the automatic refresh leaves your certificate alone), replace /etc/ssl/aliasvault/aliasvault.crt and /etc/ssl/aliasvault/aliasvault.key (keep the key mode 0600, owner root), put the certificate and key together in /opt/aliasvault/certificates/smtp/aliasvault.pem (mode 0600) for STARTTLS, then run sudo systemctl reload nginx and sudo systemctl restart aliasvault.

Step 9: Check the security controls

The certificate was made for this instance on first boot, every container's traffic to the instance metadata service is dropped, and nginx, Docker and AliasVault's own unit are denied it as well. The containers drop their capabilities, the secret files are readable only by root (the database password also by the PostgreSQL user, 70), and the last line sends a request to the metadata service from inside the API container:

H=$(sudo sed -n 's/^set \$app_host "\(.*\)";$/\1/p' /etc/nginx/aliasvault-host.conf)
openssl s_client -connect 127.0.0.1:443 -servername "$H" </dev/null 2>/dev/null | openssl x509 -noout -subject -enddate
sudo iptables -S DOCKER-USER | grep DROP
systemctl show -p IPAddressDeny --value nginx.service docker.service aliasvault.service
sudo docker inspect --format '{{.Name}} user={{.Config.User}} cap_drop={{.HostConfig.CapDrop}} cap_add={{.HostConfig.CapAdd}}' aliasvault-postgres aliasvault-client aliasvault-api aliasvault-admin aliasvault-smtp aliasvault-task-runner
sudo ls -ln /opt/aliasvault/secrets/
out=$(sudo docker exec aliasvault-api wget -q -T 5 -O - http://169.254.169.254/latest/meta-data/ 2>&1); echo "$out"; [[ "$out" == *"timed out"* ]]

subject=CN = ec2-44-207-6-221.compute-1.amazonaws.com, O = cloudimg
notAfter=Jan 22 08:53:39 2029 GMT
-A DOCKER-USER -d 168.63.129.16/32 -j DROP
-A DOCKER-USER -d 169.254.169.254/32 -j DROP
169.254.169.254/32 168.63.129.16/32

169.254.169.254/32 168.63.129.16/32

169.254.169.254/32 168.63.129.16/32
/aliasvault-postgres user=70:70 cap_drop=[ALL] cap_add=[]
/aliasvault-client user= cap_drop=[ALL] cap_add=[CAP_CHOWN CAP_SETGID CAP_SETUID]
/aliasvault-api user= cap_drop=[ALL] cap_add=[]
/aliasvault-admin user= cap_drop=[ALL] cap_add=[]
/aliasvault-smtp user= cap_drop=[ALL] cap_add=[]
/aliasvault-task-runner user= cap_drop=[ALL] cap_add=[]
total 20
-rw------- 1 0  0  64 Oct 20 08:53 abuse_metrics_salt
-rw------- 1 0  0 105 Oct 20 08:53 admin_password_hash
-rw------- 1 0  0  41 Oct 20 08:53 data_protection_cert_pass
-rw------- 1 0  0  45 Oct 20 08:53 jwt_key
-rw-r----- 1 0 70  33 Oct 20 08:53 postgres_password
wget: download timed out

To allow the admin panel only from your own networks, edit /etc/nginx/aliasvault-admin-allow.conf (it ships with allow all;) and reload nginx. The admin password is still required:

allow 203.0.113.0/24;
deny all;

sudo nginx -t && sudo systemctl reload nginx

Step 10: Registration, admin password and settings

• Open registration (for a public service): set PUBLIC_REGISTRATION_ENABLED=true in /opt/aliasvault/.env and run sudo systemctl restart aliasvault. Anyone who can reach port 443 can then create an account; AliasVault limits registrations per address per day.
• New admin password: sudo aliasvault-reset-admin-password generates one, installs its hash, restarts the admin panel (which also clears admin two-factor authentication and any lockout), proves the new login and writes it to /root/aliasvault-credentials.txt.
• Settings such as the support email shown to users (SUPPORT_EMAIL) and the upload limit (MAX_UPLOAD_SIZE_MB) are in /opt/aliasvault/.env. That file holds settings only and must stay mode 0600; AliasVault refuses to start if a secret is placed in it. Server settings such as registration limits and log retention are in the admin panel under Server settings.

Maintenance

• Logs: sudo docker logs aliasvault-api (and -admin, -smtp, -task-runner, -client, -postgres), the admin panel's General logs and Auth logs, /var/log/nginx/ for HTTPS access, and sudo journalctl -u aliasvault-firstboot.service -u aliasvault-postboot.service for first boot.
• Restart: sudo systemctl restart aliasvault (all six containers), or sudo systemctl restart nginx.
• Backups: the vaults are encrypted, so a database dump is safe to store, but it is still your users' data: sudo docker exec aliasvault-postgres pg_dump -U aliasvault aliasvault | gzip > aliasvault.sql.gz. Also keep /opt/aliasvault/secrets/ (root only) and take EBS snapshots of the volume.
• Operating system updates: Ubuntu's unattended security upgrades stay on, so nginx, Docker and the rest of the OS keep receiving patches. Apply the rest with sudo apt update && sudo apt upgrade in a maintenance window.
• Upgrading AliasVault: the images are pinned by digest and first boot never pulls. Read the release notes (a new vault format needs every app updated too), take a database backup, pull the six images of the new release by digest (sudo docker pull ghcr.io/aliasvault/<service>:<version>@sha256:<digest>), change the image: lines in /opt/aliasvault/docker-compose.yml and run sudo systemctl restart aliasvault. The API migrates the database on start. Keep the cap_drop, security_opt, per-file secret mounts and loopback ports settings, and never use host networking, which would bypass both nginx and the metadata firewall rule.

Troubleshooting

The admin sign-in says Invalid login attempt. Use admin and ALIASVAULT_ADMIN_PASSWORD from /root/aliasvault-credentials.txt exactly. After 10 wrong passwords the account is locked for 30 minutes; sudo aliasvault-reset-admin-password sets a new password and clears the lockout. After many quick attempts nginx answers 429 for a short while.

The invite link says it is invalid. Each link can create the number of accounts it was made for and expires after the days you chose. Create a new one under Users > + Invite. Usernames are 3 to 40 characters; if Continue stays greyed out, the name is taken or still being checked.

nginx is not running. On a new instance it waits until first boot has proved the admin password, by design. Check with sudo journalctl -u aliasvault-postboot.service --no-pager | tail -20 and sudo systemctl status aliasvault.

AliasVault does not start after an edit. sudo journalctl -u aliasvault --no-pager | tail -20 shows the start-up check's reason (for example a secret placed in .env, or a secret file's mode).

Mail does not arrive. Check the MX record, that the domain is in PRIVATE_EMAIL_DOMAINS, that the security group allows TCP 25, and sudo docker logs aliasvault-smtp.

Support

cloudimg provides 24/7 support for this image by email and live chat: launching and connecting, accounts and invites, email aliases and DNS, TLS and hostnames, and upgrades.

AliasVault is developed by the AliasVault project and is released under the GNU Affero General Public License v3.0. The licence text and a written offer of the corresponding source ship on the instance in /usr/share/doc/aliasvault/. PostgreSQL is released under the PostgreSQL Licence. Ubuntu is a registered trademark of Canonical Ltd. Docker is a trademark of Docker, Inc. All other product and company names are trademarks or registered trademarks of their respective holders. cloudimg is not affiliated with or endorsed by them.