Start here

Docker

Elowen does not include a maintained production Docker image or Compose file. If you containerize it, you own the image, process supervision, networking, and upgrades. The standard installer instead uses native services managed by systemd.

Build the daemon and Web UI from the source checkout using the Node.js version required by Install. Run the daemon and Web UI as separate long-running processes, on port 4400 and 4500 by default unless ELOWEN_PORT or ELOWEN_WEB_PORT says otherwise; publish only the Web UI port. Keep the daemon private unless you deliberately need direct access; normally, users reach it through the Web UI and configured reverse proxy.

Keep data between containers

Elowen keeps its state in two places. Persist both.

The PostgreSQL database that ELOWEN_DATABASE_URL points to. It holds settings, accounts and conversation history. Run it as its own service with a persistent volume.
The instance folder, ELOWEN_INSTANCE_ROOT, by default ~/.config/elowen/ ($HOME/.config/elowen). It holds the setup marker, CLI preferences, saved plans, the encryption key for plugin credentials plugin-secrets.key, licence.json, the user plugin folder plugins/, plugin data in plugins-data/, and the runtime folders such as brain/, marketplace/, update/, plugin-installs/, chat-images/, and chat-files/.

The database server must be PostgreSQL 16 or newer with the vector (0.7 or newer) and pg_trgm extensions installed in the database and pg_stat_statements in shared_preload_libraries. The role Elowen connects with must be able to create schemas, and a URL that reaches the database over TCP must carry sslmode=verify-full.

The instance folder must be an absolute path that is not a top-level directory, so mount it at a subdirectory such as /var/lib/elowen rather than at /elowen.

The database and the instance folder with its encryption key must be backed up and restored as a pair. Back up both before changing versions. A restored database without its key cannot read the stored plugin credentials.

Mount each repository at a stable path inside the container, then register that same container path as its Project. A host path and a container path are different locations.

First run and upgrades

Run elowen setup with HOME pointing at the persistent volume, so the instance folder is stored there, or set ELOWEN_INSTANCE_ROOT to a folder on that volume. Set ELOWEN_DATABASE_URL for the daemon. For an upgrade, build a new image and recreate the services while keeping both locations. The daemon applies database migrations when it starts.

See Install and Production & Updates.