Athenode

Athenode Pro with Docker Compose

Athenode Pro with Docker Compose is a stack of containers that the Self-hosting configurator in your Athenode account generates from your options, and that runs Athenode Pro, its database and its reverse proxy on one server. Athenode Pro is the Athenode server a team runs itself, with accounts, project roles and a licence. Athenode publishes no Docker image of Pro: the stack builds the image on your server, from the @athenode/athenode-pro package on a public Node.js image, with your organisation's install token. Install Athenode Pro describes the install without containers.

Check the server requirements

The server that runs the stack needs:

  • Docker Engine with the Compose plugin, version 2, and BuildKit.
  • At least 2 CPU cores, 4 GB of memory and 20 GB of disk, and more for large teams or long audit histories.
  • An organisation in your Athenode account with an active subscription to a Pro tier, as Billing for Athenode Pro describes.
  • For an external database, PostgreSQL 15 or later, prepared as Install Athenode Pro describes.

The services of the stack set no CPU or memory limits. To add some, put a deploy section on a service in compose.yaml:

services:
  athenode-pro:
    deploy:
      resources:
        limits:
          cpus: "2"
          memory: 2G

Generate the stack in the console

Generate the stack once for each server. You need to be a billing administrator of an organisation whose Pro licence is active. Without an active Pro plan, the section says "Self-hosting Athenode Pro needs an active Pro plan." and links to the organisation's licence.

  1. In your Athenode account, open Organisations and select the organisation.
  2. Open Self-hosting.
  3. Fill in the form. Enter the Domain your team opens, such as pro.example.com, and the First administrator’s email. The configurator generates the passwords in your browser.
  4. Under Licence, paste a licence token of the organisation, or select Create licence token to create one named after the domain.
  5. Under Install token, paste the organisation's install token. To replace it, select Create new, then Revoke and create: the current install token stops working, and other installations that use it can no longer download Pro updates until they get the new one.
  6. Check the files in the preview, which changes with every option.
  7. Select Download zip.

The zip is built in your browser, and nothing you enter is sent to the server. It holds these files, depending on the options:

File What it holds
compose.yaml The services, volumes and build secrets
.env Every value compose.yaml reads, secrets included
pro/Dockerfile The image of Athenode Pro, installed from your organisation's package registry at build time
postgres/Dockerfile PostgreSQL 18, when the stack runs the database
caddy/Dockerfile, caddy/Caddyfile Caddy, the reverse proxy with automatic TLS certificates
backup/Dockerfile, backup/entrypoint.sh, backup/backup.sh The scheduled backup service
license.key The signed licence key, on a server without internet access
README.md Starting, backing up, updating and restoring this stack
configurator.json The options, without any secret

To change the stack later, select Load configurator.json on the same page, change the options and download it again. The file holds no secret, so fill in the licence, the install token and any API key again. New passwords are generated, so keep the values of the running stack's .env where they matter, such as the database password.

Choose the database and the proxy

The configurator runs PostgreSQL 18 in the stack by default, with its data in a volume. Clear Run PostgreSQL in the stack to use your own database instead, whose address goes into ATHENODE_DATABASE_URL. The backup service and search by meaning need the database in the stack.

With Run Caddy in the stack for HTTPS with automatic certificates, Caddy gets a TLS certificate for the domain at the first start. Point the domain's DNS record at the server and open ports 80 and 443 first. Without Caddy, Pro is published on 127.0.0.1 at the Local port, 3717 by default, and your own reverse proxy terminates TLS in front of it. List the proxy's address as the container sees it in ATHENODE_TRUSTED_PROXIES: for a proxy on the same host, that is the gateway address of Docker's network. The proxy meets the requirements of the reverse proxy of Athenode Pro.

Prepare the .env file

.env holds every value of the stack, with the required ones first, and the configurator fills it in from the form. It holds the database password, the licence token and the first administrator's password, so make it readable by your user only:

chmod 600 .env

The install token is a build secret. The build reads it once to install Pro and never writes it into the image or the container's environment.

Start the stack for the first time

  1. Unzip the stack into a folder on the server and open a terminal there.

  2. Build and start it:

    docker compose up -d --build

  3. Wait until docker compose ps shows the athenode-pro service as healthy. The first start sets up the database and can take a minute.

At its first start, Pro activates the licence from ATHENODE_LICENSE_TOKEN. On a server without internet access, select Air-gapped: the server has no internet access and Load signed key in the configurator instead: the stack mounts license.key into the container and sets ATHENODE_LICENSE_KEY_FILE to it. The Pro licence describes both ways, and when Pro ignores the variables.

A signed key is valid for one billing period, and Pro imports it at start only while no stored licence works. For each new billing period:

  1. Download the new key of the organisation, as download the licence key describes.

  2. Replace the contents of license.key in place, so that the container sees the new key:

    cat new.key > license.key

  3. Import it in the running container:

    docker compose exec athenode-pro athenode-pro license import --file /run/athenode/license.key

Pro also creates the first administrator from ATHENODE_ADMIN_EMAIL and ATHENODE_ADMIN_PASSWORD, as Install Athenode Pro describes.

  1. Open your domain, such as https://pro.example.com, and sign in with the email and the initial password from .env.

  2. Change the password, as Pro asks at the first sign-in.

  3. Remove both variables from .env, or empty them.

  4. Apply the change:

    docker compose up -d

Run the commands of athenode-pro in the running container, such as:

docker compose exec athenode-pro athenode-pro doctor
docker compose exec athenode-pro athenode-pro license status

Never use docker compose run for them: it starts a second container, and Pro refuses its lock while the server runs. docker compose logs -f athenode-pro shows the log.

Add the backup service

The backup service backs up the database and the master key on a schedule. Select Back up the database on a schedule in the configurator, which needs the database in the stack. Its settings are in .env:

Variable What it sets Default
BACKUP_SCHEDULE A cron schedule, in UTC unless TZ is set in .env 0 3 * * *, every day at 03:00
BACKUP_KEEP_DAYS The days a backup is kept before it is deleted 7
BACKUP_DIR The folder on the host the backups go to ./backups

Each run writes a pg_dump -Fc dump of the database and a copy of master.key, named with the run's time. A dump is useless without the master key of the same installation, so copy the backups off the server and store the key copies apart from the dumps. To back up now, for example before an update:

docker compose exec backup backup.sh

Back up Athenode Pro describes what the two parts hold. The README.md of the stack has the restore commands.

Turn on search by meaning

Search by meaning finds specifications that describe the same thing in other words. Turn it on in the configurator, which needs the database in the stack. The stack's PostgreSQL then comes with the extension the search needs.

Choose where the model runs:

  • Ollama in the stack: an Ollama service runs the model you choose. The stack pulls the model before Pro starts, which needs internet access, so a server without internet access cannot use it. With Use the host’s NVIDIA GPUs, Ollama uses the server's NVIDIA GPUs, which needs the NVIDIA Container Toolkit on the host. On a CPU, indexing many specifications can be slow.
  • External API: a hosted provider, or another OpenAI-compatible API in your network, with its API key in .env.

Configure Athenode Pro describes the settings of the search.

Keep the data volume safe

Pro keeps its data folder in /data of the container, ATHENODE_PRO_HOME, on the athenode-data volume. The folder holds master.key, which Pro creates at its first start, config.json and the log. The master key encrypts the secrets Pro stores in the database, such as SSH credentials and the licence token. Without it, those secrets cannot be read, so back it up with the database, and never remove the volume with docker compose down -v.

Without the backup service, copy the key out of the container:

docker compose cp athenode-pro:/data/master.key ./master.key

Update Athenode Pro

The update builds the image again with the newest version from the package registry. Pro updates the database at its first start and takes no backup itself.

  1. Back up the database and the master key.

  2. Build the new image:

    docker compose build --pull --no-cache athenode-pro

  3. Restart Pro:

    docker compose up -d

To pin a version, set ATHENODE_PRO_VERSION in .env, as in ATHENODE_PRO_VERSION=<version>, and build the same way. latest, the default, takes the newest version. Pro refuses a database that a newer version has updated, so going back means restoring the backup, as Upgrade Athenode Pro describes.

Move to PostgreSQL 19 later

The stack runs PostgreSQL 18, with its data in the postgres-data volume. A new major version cannot read that data in place, so the move goes through a dump.

  1. Dump the database, as the backup service or the README.md of the stack does.
  2. Stop the stack with docker compose down.
  3. Change the image in postgres/Dockerfile to postgres:19, and in backup/Dockerfile too when the stack has the backup service. With search by meaning, also change postgresql-18-pgvector in postgres/Dockerfile to postgresql-19-pgvector.
  4. Point the database service at a new, empty volume.
  5. Start the database alone with docker compose up -d --build postgres.
  6. Restore the dump with pg_restore.
  7. Start the stack with docker compose up -d.

Never point PostgreSQL 19 at the old volume.