Installation

This guide walks through a fresh Atrium self-hosted installation. By the end, you'll have a running Atrium instance with HTTPS, a database, and an initial admin account.

Overview

The installation consists of:

1. Downloading the configuration package from the Control Plane.
2. Editing the .env file with your settings.
3. Running the setup script.

The configuration package contains everything you need: a Docker Compose file, Traefik configuration, environment template, and a setup script. It's generated specifically for your instance by the Control Plane.

Step 1: Prepare the server

Ensure Docker and Docker Compose are installed:

# Ubuntu / Debian
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in for group membership to take effect

# Verify
docker compose version

Step 2: Obtain the configuration package

Your Atrium account includes access to the Control Plane, where you can download the configuration package for your instance:

1. Log in to the Control Plane portal.
2. Navigate to your instance.
3. Click Download Configuration Package.
4. Transfer the package to your server and extract it.

# On the server
mkdir -p ~/atrium && cd ~/atrium
# Extract or place the configuration files here

The package contains:

File	Purpose
docker-compose.yaml	Service definitions (backend, frontend, PostgreSQL, NATS, WeasyPrint, Traefik)
traefik.yaml	Traefik static configuration (entrypoints, ACME)
.env	Environment variables (needs editing)
setup.sh	Automated setup script
README.md	Quick reference

Step 3: Configure environment

Edit the .env file:

nano .env

Required settings:

Variable	Description
DOMAIN	Your domain name (e.g., atrium.yourcompany.com)
ACME_EMAIL	Email for Let's Encrypt certificate notifications
POSTGRES_PASSWORD	Database password (pre-generated, change if desired)
JWT_SECRET	Token signing secret (pre-generated, do not share)

Optional settings:

Variable	Description	Default
SMTP_HOST	SMTP server for email notifications	(none — emails disabled without SMTP)
SMTP_PORT	SMTP port	587
SMTP_USER	SMTP username
SMTP_PASS	SMTP password
SMTP_FROM	Sender email address	noreply@{DOMAIN}

Step 4: Run the setup script

chmod +x setup.sh
./setup.sh

The setup script:

1. Verifies Docker and Docker Compose are installed.
2. Pulls container images from ghcr.io.
3. Starts the stack (docker compose up -d).
4. Waits for PostgreSQL to be ready.
5. Runs database migrations.
6. Creates the initial admin account.
7. Prints the admin credentials.

Save the admin credentials displayed at the end. You'll need them to log in.

Step 5: Verify

Open https://<your-domain> in a browser.

• The first request may take a moment while Traefik obtains the TLS certificate from Let's Encrypt.
• Log in with the admin credentials from the setup script.
• You should see the dashboard.

If the site doesn't load, check the Troubleshooting section below.

Troubleshooting

HTTPS not working (certificate error):

• Verify the domain's DNS A record points to the server's IP: dig +short A your-domain.com
• Check Traefik logs: docker logs atrium-traefik
• Let's Encrypt rate limits: if you've requested many certificates recently, you may be rate-limited. Wait an hour and try again.

Database connection error:

• Verify PostgreSQL is running: docker ps | grep postgres
• Check PostgreSQL logs: docker logs atrium-postgres

Container won't start:

• Check available disk space: df -h
• Verify Docker is running: systemctl status docker
• Pull images manually: docker compose pull

What's next

• Configure TLS if you need custom certificates instead of Let's Encrypt.
• Set up backups before going to production.
• Configure SMTP for email notifications.
• Add users and configure sites.