aliasvault/docs/installation/docker-compose/index.md

layout, title, parent, redirect_from, nav_order

layout	title	parent	redirect_from	nav_order
default	Docker Compose	Self-host Install	/installation/advanced/manual-setup /installation/advanced/manual-setup.html	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.

Table of contents

{: .text-delta } 1. TOC {:toc}

{: .important-title }

Requirements:

• Docker (20.10+) and Docker Compose (2.0+) installed on your system
• See instructions: https://docs.docker.com/engine/install/
• You have existing SSL/TLS 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.

mkdir aliasvault
cd aliasvault

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.

services:
  aliasvault:
    image: ghcr.io/aliasvault/aliasvault:latest
    container_name: aliasvault
    restart: unless-stopped

    ports:
      - "80:80"
      - "443:443"
      - "25:25"
      - "587:587"

    volumes:
      - ./database:/database
      - ./logs:/logs
      - ./secrets:/secrets
      - ./certificates:/certificates

    environment:
      HOSTNAME: "localhost"
      PUBLIC_REGISTRATION_ENABLED: "true"
      IP_LOGGING_ENABLED: "true"
      FORCE_HTTPS_REDIRECT: "false"
      SUPPORT_EMAIL: ""
      PRIVATE_EMAIL_DOMAINS: ""
      SMTP_TLS_ENABLED: "false"

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:

   • 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/TLS configuration

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

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.

---

3. Email Server Setup

AliasVault includes a built-in email server that allows you to generate email aliases on-the-fly for every website you use, and receive 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.

Requirements

• 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:

# Test standard SMTP port
telnet <your-server-public-ip> 25

# Test secure SMTP port
telnet <your-server-public-ip> 587

DNS configuration

Choose your configuration: primary domain vs subdomain. AliasVault can be configured under:

• A primary (top-level) domain Example: your-aliasvault.net. This allows you to receive email on %alias%@your-aliasvault.net.

• A subdomain of your existing domain Example: aliasvault.example.net. This allows you to receive email on %alias%@aliasvault.example.net. Email sent to your main domain remains unaffected and will continue arriving in your usual inbox.

---

a) Setup using a primary domain

Configure the following DNS records on your primary domain (e.g. your-aliasvault.net):

Name	Type	Priority	Content	TTL
mail	A		<your-server-public-ip>	3600
@	MX	10	mail.your-aliasvault.net	3600

Replace <your-server-public-ip> with your actual server IP.

Example

• mail.your-aliasvault.net points to your server IP.
• Email to @your-aliasvault.net will be handled by your AliasVault server.

---

b) Setup using a subdomain

Configure the following DNS records on your subdomain setup (for example, aliasvault.example.com):

Name	Type	Priority	Content	TTL
mail.aliasvault	A		<your-server-public-ip>	3600
aliasvault	MX	10	mail.aliasvault.example.com	3600

🔹 Explanation:

• mail.aliasvault creates a DNS A record for mail.aliasvault.example.com pointing to your server IP.
• The MX record on aliasvault.example tells senders to send their mail addressed to %@aliasvault.example.com to mail.aliasvault.example.com.

Replace <your-server-public-ip> with your actual server’s IP address.

Example

• mail.aliasvault.example.com points to your server IP.
• Emails to user@aliasvault.example.com will be handled by your AliasVault server.

This keeps the email configuration of your primary domain (example.com) completely separate, so you can keep receiving email on your normal email addresses and have unique AliasVault addresses too.

---

AliasVault server email domain configuration

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:

# ...
    environment:
      PRIVATE_EMAIL_DOMAINS: "yourdomain1.com,yourdomain2.com"
# ...

After updating the docker-compose.yml file, restart the Docker Compose stack:

# To apply new environment variables, containers must be recreated.
docker compose down
docker compose up -d

Afterwards, when you login to the AliasVault web app, you should now be able to create an alias with your configured private domain and be able to receive email on it.

{: .note } 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 to get help from other users and maintainers.

Optional: SMTP TLS (STARTTLS)

By default, SMTP TLS is disabled (SMTP_TLS_ENABLED: "false"). This does NOT significantly impact email deliverability: most email providers will still deliver to your server. However, if you want to enable TLS for SMTP connections:

1. Obtain a valid TLS certificate for your mail hostname (e.g., mail.example.com)
2. Combine the certificate and private key into a single .pem file
3. Place the .pem file in your ./certificates/smtp/ volume directory
4. Update your docker-compose.yml to set SMTP_TLS_ENABLED: "true"
5. Restart the container: docker compose down && docker compose up -d

{: .note } If you have multiple mail domains, use a single certificate with Subject Alternative Names (SANs) covering all domains. If TLS is enabled but no valid certificate is found, the service will log a warning (visible in admin panel > general logs) and continue in non-TLS mode.

---

4. Troubleshooting

For more detailed troubleshooting information, please refer to the troubleshooting guide.