Install Athenode Pro

Athenode Pro is the Athenode server a team runs itself, with accounts, project roles and a licence. You install it from the @athenode/athenode-pro package with your organisation's install token, give it a PostgreSQL database, activate its licence and run it under a supervisor of your choice, behind a reverse proxy that terminates TLS. Athenode Pro describes what the server adds to the local daemon.

The server needs:

Node.js 22.16 or later.
PostgreSQL 15 or later, with its contrib modules installed on the database server.
An organisation in your Athenode account with an active subscription to a Pro tier, as Billing for Athenode Pro describes.
A reverse proxy that terminates TLS for the address your team opens, which Configure Athenode Pro describes.

Tip

To run Pro in containers, generate a ready-to-run stack in your Athenode account instead, as Athenode Pro with Docker Compose describes.

Install the package with the install token

The install token is the token of an organisation that installs Athenode Pro. Install with it on the machine that runs the server, as the user that will run it. You need to be a billing administrator of the organisation to create the token.

In your Athenode account, open Organisations and select the organisation.
In the Install token panel, select Create install token. If the organisation already has a token, the button is Rotate install token, and the old token stops working.
The Install token created dialog shows three parts: Token, .npmrc and Install command. The token is shown only once, so keep the dialog open until you have finished the next two steps.
Copy the lines under .npmrc into the ~/.npmrc file of the user that installs Pro. Use the lines as the dialog shows them, and add no line of your own for the @athenode scope, because installs of the public @athenode/cli package on this machine may then fail.
Run the line under Install command in a terminal of the same user.
Check the installed version:
```
athenode-pro version
```

The token can only read the package registry. The line in ~/.npmrc keeps it for later upgrades on this machine. Keep a copy of the install command with your server notes: it holds no token, and you run it again for every upgrade. Licence and install tokens describes rotating and revoking the token, and what happens to it when the subscription ends. Revoking the token stops new installs and upgrades, and installed servers keep running.

Prepare the PostgreSQL database

Pro keeps its projects, accounts and settings in one PostgreSQL database. Run one Pro server per database.

As a PostgreSQL superuser, create a role for Pro and a database that the role owns:

CREATE ROLE athenode LOGIN PASSWORD 'choose-a-password';
CREATE DATABASE athenode OWNER athenode;

Put the connection address in ATHENODE_DATABASE_URL, in the environment of the user that runs Pro:
```
export ATHENODE_DATABASE_URL=postgres://athenode:choose-a-password@db.internal:5432/athenode
```

A role that owns its database has every right Pro needs. If your database is owned by another role, Pro's role needs the right to create in it:

GRANT CREATE ON DATABASE athenode TO athenode;

Pro sets up its tables on its first start and needs the pg_trgm extension, which comes with the contrib modules. When a right or the extension is missing, Pro stops before it changes anything, with a message that names what is missing and the statement that grants it. Where your role may not create extensions, a superuser can run CREATE EXTENSION pg_trgm; in the database once.

Search by meaning needs a second extension, which a superuser creates. Configure Athenode Pro describes it with the rest of the search settings.

Activate the licence

Pro starts only with a valid licence key of your organisation. Activate it once before the first start, as the user that runs Pro, with a licence token that a billing administrator created in the organisation's License panel:

ATHENODE_LICENSE_TOKEN=<licence-token> athenode-pro license activate

license activate needs only ATHENODE_DATABASE_URL. On a new installation it creates the master key in Pro's data folder, ~/.athenode-pro, and prints its path. The master key encrypts the secrets Pro stores. Back it up at once, as Back up Athenode Pro describes. The Pro licence covers the other ways to pass the token, an offline key and the licence states.

Pro can also activate the licence at start, from ATHENODE_LICENSE_TOKEN in its environment, or on a server without internet access from ATHENODE_LICENSE_KEY_FILE, the path of a signed licence key. It does so only while no stored licence works, and setting both variables stops the start. Once a licence is stored, Pro ignores both, so switch to another licence with license activate. The Pro licence describes activation at start.

Without a valid key, athenode-pro start exits with "Athenode Pro cannot start: No valid Athenode Pro license" and names the commands that fix it.

Run Athenode Pro under a supervisor

Pro runs in the foreground: athenode-pro start keeps running until it receives a stop signal or you run athenode-pro stop. It does not install itself as a service, so run it under a process supervisor of your own, such as systemd, which starts it at boot and restarts it after a failure. Run it as a dedicated user, because its data folder is in that user's home folder.

start needs the public URL, the https address your team opens, and the database. Give it the address of your reverse proxy as a trusted proxy. Configure Athenode Pro lists every flag and variable and the requirements for the proxy.

A systemd unit, /etc/systemd/system/athenode-pro.service, for a user athenode:

[Unit]
Description=Athenode Pro
After=network-online.target postgresql.service
Wants=network-online.target

[Service]
User=athenode
EnvironmentFile=/etc/athenode-pro.env
ExecStart=/usr/local/bin/athenode-pro start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

The environment file, /etc/athenode-pro.env, readable only by root and the athenode user because it holds the database password:

ATHENODE_DATABASE_URL=postgres://athenode:choose-a-password@db.internal:5432/athenode
ATHENODE_PUBLIC_URL=https://athenode.example.com
ATHENODE_TRUSTED_PROXIES=10.0.0.2

Replace /usr/local/bin/athenode-pro with the path that command -v athenode-pro prints for the athenode user.

Load and start the unit:

sudo systemctl enable --now athenode-pro

Check the server as the athenode user, with the same environment:
```
athenode-pro doctor
```

doctor checks the configuration, the database and its extensions, the licence and the running instance. athenode-pro status exits with 0 while the server runs. Pro writes its log to logs/athenode.log in the data folder. A supervisor's stop signal stops Pro the same way as athenode-pro stop.

Create the first administrator

While the server has no administrator, every start prints the address of the setup page, the public URL followed by /setup, and a one-time setup token. The same line goes to logs/athenode.log. Each start makes a new token and the earlier one stops working. A token is valid for 24 hours.

Find the setup token in the console output of the start, or in ~/.athenode-pro/logs/athenode.log of the user that runs Pro. Under systemd, the console output is in journalctl -u athenode-pro.
Open https://athenode.example.com/setup, with your public URL.
Enter the Setup token, Your name, Email and a Password of at least 12 characters.
Select Create the administrator.

You are signed in as the first administrator, and the account takes the first seat. The setup page then shows "Already set up", and new accounts join through an invitation. Until the setup is done, the setup token in the log gives anyone who reads it the first administrator account, so keep the data folder readable by the Pro user only. Users and sign-in continues with email, single sign-on, the two-factor policy and invitations.

To create the administrator without the setup page, set ATHENODE_ADMIN_EMAIL and ATHENODE_ADMIN_PASSWORD in the environment of the server. Pro then creates the first administrator at start while it has none, and prints no setup token. Set both variables or neither: an empty value counts as unset, and with only one of them set Pro refuses to start. The password is an initial one, and at the first sign-in Pro asks for a new password that differs from it. After the first sign-in, remove both variables. Without them, the setup page and its token stay the way to create the first administrator.

Upgrade Athenode Pro

Pro shows its administrators a notice above every page when a newer version is released. Members do not see it. Pro takes no backup of the database before it upgrades it, so back up first.

Back up the database, as Back up Athenode Pro describes.
Run the install command of the Install token created dialog again, as the user that installed Pro.
Restart the server, with sudo systemctl restart athenode-pro or by running athenode-pro stop and starting it again.
Run athenode-pro doctor to check the new version.

The first start of the new version updates the database for it. An older version of Pro refuses a database that a newer version has updated, and its message names the version to install. To go back to the earlier version, restore the database backup you took in step 1 and install that version. Without a backup from before the upgrade, the database stays on the new version.

Athenode Pro 0.13.0 and later accept only v3 licence keys. A server with a stored licence token gets its v3 key at the first start of the new version. A server that imports its key by hand needs a v3 key imported before that start, as the v3 licence key describes.

Back up Athenode Pro

A backup of Pro has two parts, and you need both to restore it.

Part	What it holds	How to back it up
The PostgreSQL database	Projects, specifications, ToDo cards, plugins, SSH connections, accounts, settings, the audit	With your usual PostgreSQL backup, such as `pg_dump`, before every upgrade and on a schedule
The master key, `~/.athenode-pro/master.key`	The key that encrypts the secrets stored in the database	Copy the file once, to a place apart from the database backup

The master key encrypts the SSH credentials, the webhook and audit forwarding secrets, the two-factor secrets, the SMTP password, the single sign-on client secret, the licence token, the library sign-ins and the tokens for imports. If you set the key with ATHENODE_MASTER_KEY or ATHENODE_MASTER_KEY_FILE, back up that value or file instead, as Configure Athenode Pro describes.

Without the master key, those secrets cannot be read. Pro then refuses to start with a database that holds secrets, and asks you to restore the key into the data folder. It never creates a new key over existing secrets. Keep the key backup apart from the database backup, because together they give access to every stored secret.

To restore, load the database backup into an empty database, put master.key back into the data folder of the Pro user, and start Pro. athenode backup and athenode restore are commands of the local daemon and do not apply to Pro.

Last updated: 2026-10-31