Installation
Athena Server ships as a single Docker container that serves the web console on
port 8443 and the agent gateway on port 8444. Pull the image,
mount your data volumes, and run it behind your own TLS — that is the only supported
deployment method.
Prerequisites#
- A Linux or Windows host running Docker.
- Two open TCP ports for the host:
8443(web/API) and8444(agent gateway, gRPC over HTTP/2). - TLS is handled for you — on first start the server issues its own certificate from its Root CA, and Kestrel serves HTTPS directly on both ports. To use a CA-issued certificate instead, see Server TLS Certificate.
- Persistent disk for the data volumes listed below.
Nothing here requires internet access. Transfer the container image (e.g. docker save/docker load) and your agent binaries onto the isolated network, then run exactly as below. See Air-Gapped Operation.
Run with Docker#
The container runs as a non-root user. Create the data directories and run it — configuration is supplied as environment variables, and the server issues its own TLS certificate on first start:
# 1. Create persistent directories on the host
mkdir -p /opt/athena/{data,pki,logs,backups,certs,packages,agent-binaries}
# 2. Run the server — it generates its own TLS certificate on first start
docker run -d \
--name athena-server \
--restart unless-stopped \
-p 8443:8443 \
-p 8444:8444 \
-v /opt/athena/data:/app/data \
-v /opt/athena/pki:/app/pki \
-v /opt/athena/logs:/app/logs \
-v /opt/athena/backups:/app/backups \
-v /opt/athena/certs:/app/certs \
-v /opt/athena/packages:/app/packages \
-v /opt/athena/agent-binaries:/app/agent-binaries \
ghcr.io/<owner>/athena-server:latestThe container exposes:
| Path inside container | Purpose |
|---|---|
/app/data | Database file (SQLite default) and app state |
/app/pki | Root CA and issued agent certificates |
/app/packages | Uploaded deployment packages |
/app/agent-binaries | Agent installers served for enrollment & self-update |
/app/certs | Server TLS certificate — auto-generated, or your own if supplied |
/app/logs | Application log files |
/app/backups | Database backups |
Athena defaults to SQLite and generates its TLS certificate on first start, so no extra
configuration is needed to come up. The healthcheck calls https://localhost:8443/health.
Behind a reverse proxy, NAT, or port mapping? Add
-e Server__PublicUrl=https://athena.example.com:8443 so the server stamps the
correct externally-reachable address into the agent installers it generates. If you omit it,
Athena derives that address from the inbound request host. Any other setting can be passed the
same way — see Configuration.
First run#
On its first start the container generates its Root CA (and a server TLS
certificate signed by it), seeds the default admin account from the DefaultAdmin
config section, and runs database schema migrations automatically. Once the healthcheck reports
healthy, the console is reachable at:
- Web UI / API:
https://<host>:8443 - Agent gateway:
https://<host>:8444
First sign-in#
- Browse to
https://<host>:8443. - Sign in as the default admin — username
admin(unless you setDefaultAdmin__Username). - Change the password immediately after signing in — the policy requires at least 8 characters with upper, lower, and a digit.
- Continue to Agent Enrollment to bring your first endpoint online.
If you set DefaultAdmin__Password, that is the password. Otherwise, on first
start Athena generates a secure random password for the admin account and writes
it to the server log. Read it from the container logs:
docker logs athena-server 2>&1 | grep -A2 "DEFAULT ADMIN USER CREATED"Look for the DEFAULT ADMIN USER CREATED banner, which prints the username and
the generated password. The log is also persisted in the /app/logs volume. It is
shown once, at creation — so grab it before changing the password.
Sessions time out after 3 minutes of inactivity and accounts lock after 5 failed sign-ins by default. Both are tunable in the Security config section.