ATHENA.

Installation & deployment

One Docker image, one MariaDB container. There's no source checkout and no separate database setup step - Athena imports its own schema the first time it starts.

What you need

  • Docker Engine + Compose plugin on any Linux x86, x86_64, or arm64 machine - a PC, a NUC, or a Raspberry Pi/SBC.
  • A LAN that supports mDNS/multicast. Device discovery and API connections need it - see ESPHome.
  • A Bluetooth adapter on the host, only if you plan to connect an IKEA IDÅSEN desk - both compose files mount the host's /var/run/dbus socket into the Athena container so it can reach BlueZ.

Choose a deploy shape

Two compose files, depending on whether you also want ESPHome's own compile/validate feature:

  • All-in-one (docker-compose-with-esphome.yml) - Athena + MariaDB + a bundled ESPHome dashboard sidecar, all on one machine. Good default for a single small box.
  • Split deploy (docker-compose.yml + docker-compose-esphome.yml) - Athena + MariaDB on this machine, the ESPHome dashboard (CPU/RAM-heavy compiles - a full ESP-IDF toolchain download + native build per device) on a separate, beefier machine, sharing device configs over a network-mounted directory. Point ESPHOME_DASHBOARD_URL at the other machine.

Deploy

1. Get the compose files

The compose files and .env.example live in github.com/makershopfi/athena - clone it, or just download the couple of files you need for your chosen deploy shape above. 

git clone https://github.com/makershopfi/athena.git
cd athena

2. Configure

# in an empty folder, next to your chosen docker-compose file
cp .env.example .env
# edit .env - set DB_PASSWORD and DB_ROOT_PASSWORD at minimum

3. Run it

Uses the pre-built image - run ./build-docker.sh <tag> first, or set TAG in .env to one already published to a registry.

docker compose up -d

This pulls the image, starts MariaDB, waits for it to report healthy, then starts Athena - which imports its own database schema automatically on that first boot. Nothing else to configure by hand. Both compose files run the athena service with network_mode: host so it can actually see LAN mDNS broadcasts, which Docker's default bridge network never gets.

4. Open it

Visit http://your-server:8080 (or whatever PORT you set in .env, default 8000). See First-time setup for what the very first screen shows.

HTTPS

Browsers only allow WebUSB/WebSerial (used by browser-USB firmware flashing) and some other browser APIs in a secure context - https:// or localhost, never plain http:// on a LAN IP or hostname. Both compose files include a bundled caddy service for this: it terminates HTTPS and proxies to Athena, using Caddy's tls internal to auto-generate and persist its own local CA + certificate - no manual certificate step.

Defaults to port 8443, not the standard 443 - that's commonly already taken by another service on a shared host. Change it with HTTPS_PORT in .env if 8443 is also taken; WebUSB/WebSerial only require the https:// scheme, not port 443 specifically, so any free port works. 

# .env
ATHENA_SECURE_COOKIES=true
HTTPS_PORT=8443

Set ATHENA_SECURE_COOKIES once the bundled Caddy service is running, or the login cookie's own Secure flag will reject sessions reaching Athena through it. Then visit https://your-server:8443 (include the port - it isn't the default HTTPS port).

Browsers will show a "not secure" warning on first visit since the bundled proxy's CA isn't in your browser's trust store - WebUSB/WebSerial only require the https:// scheme, not a publicly-trusted certificate, so clicking through once is enough. To remove the warning on a given device, export the CA (docker exec athena-caddy cat /data/caddy/pki/authorities/local/root.crt) and install it as a trusted root there.

Database engine

.env's DB_* variables only need to point at the bundled MariaDB container to get started - the choice of MariaDB/MySQL vs. your own PostgreSQL, and moving to a different database later, is a Configuration > System concern from then on, not a redeploy. See Settings.

Companion services for some integrations

A handful of integrations bridge to a separate service instead of talking to hardware directly - none of these are bundled in Athena's own compose files, since each needs its own USB stick passthrough or network visibility on whatever machine actually owns the radio:

  • Z-Wave - run Z-Wave JS UI (zwavejs/zwave-js-ui) as its own container; works with any Z-Wave USB stick, including Home Assistant's own Connect ZWA-2. Ready-made docker-compose-zwave.yml ships in Athena's own repo - see that page.
  • deCONZ - run deCONZ (deconzcommunity/deconz) as its own container on whichever machine the ConBee/RaspBee stick is plugged into. Ready-made docker-compose-deconz.yml ships in Athena's own repo - see that page.
  • Matter - run a matter-server (matterjs-server, or its archived predecessor python-matter-server) as its own container, network_mode: host. Full compose file on that page.
  • Zigbee (EZSP/bare Silicon Labs coordinator) - no separate service, just uncomment the devices: line already present (commented out) on the athena service in both bundled compose files and point it at your stick.
  • MQTT - run docker-compose-mqtt.yml (a standalone Mosquitto broker, ships in Athena's own repo) alongside whichever compose file above you're using. Full compose file on that page.

See also Zigbee2MQTT (under "Add-ons" in the sidebar) - not a dedicated Athena integration, but Zigbee gateways/devices managed by it show up automatically through the MQTT integration above, once both point at the same broker. Ready-made docker-compose-zigbee2mqtt.yml (plus a configuration.yaml.example) ships in Athena's own repo too - see that page.

Running headless

Set ATHENA_HEADLESS=true to turn off the web UI entirely - only the /api/* routes stay reachable. Useful if something else (another automation system, a mobile app) is the only thing that will ever talk to this install.

Support

Athena is a young project - expect rough edges. Questions or issues: use the contact form on the homepage.

Next → First-time setup