Docker Deployment

Raven's Compose deployment builds the WebUI and Python environment into one image. nginx serves the WebUI, while the Raven engine handles RPC, messaging channels, scheduled tasks, and other gateway services.

Start the container

To build and run the current source checkout, start from the repository root:

cd docker
docker compose up --build

To run the configured image without building the checkout, use docker compose up --no-build from docker/. Plain docker compose up may reuse or pull an image; it does not guarantee a rebuild of local changes.

Open http://127.0.0.1:18793 after the container is ready. The default local configuration signs you in automatically.

What runs in the image

The deployment runs two processes in a single container:

Process	Responsibility
nginx on port 80	Serves the built WebUI and proxies browser requests to the engine.
Raven engine	Runs the RPC gateway on 127.0.0.1:18793 inside the container.

The engine binds to loopback inside the container, so nginx and the engine stay together. The WebUI and Python environment are built from the same source checkout.

Sign in

Compose sets RAVEN_AUTO_LOGIN=1 by default, so browsers accessing the local WebUI receive a session automatically. This setting is intended for a port accessible only from the local machine.

For a remotely exposed deployment, put RAVEN_AUTO_LOGIN=0 in .env.local. The entrypoint prints a one-time sign-in URL when the container starts. The session cookie is valid for 30 days and survives container restarts because its credential is retained in the persistent data volume.

To create another sign-in URL inside the running container:

docker compose exec raven docker-entrypoint.sh signin

Configure a provider

Unless a provider is preconfigured, add one under Settings > Model providers. It becomes available on the next turn without a restart.

To configure a provider before startup, put these values in .env.local:

RAVEN_PROVIDER=anthropic
RAVEN_API_KEY=sk-ant-...

For a local provider that does not require an API key:

RAVEN_PROVIDER=ollama-chat
RAVEN_API_KEY=
RAVEN_API_BASE=http://host.docker.internal:11434

Docker Desktop provides host.docker.internal. On Linux Docker Engine, add a host-gateway mapping for that name or use a host address reachable from the container. The model server must listen on that address, with access restricted to the intended clients.

The entrypoint applies these provider values to Raven's configuration on each startup. Values set here take precedence when the container restarts.

Configure environment values

The docker/.env file contains committed defaults. For container runtime variables such as RAVEN_PROVIDER, RAVEN_API_KEY, and RAVEN_AUTO_LOGIN, the service loads the optional docker/.env.local file second as an env_file. Store credentials there; Git ignores it.

Compose interpolation is separate. RAVEN_IMAGE, RAVEN_WEB_PORT, RAVEN_EXTRAS, RAVEN_PLUGINS, and RAVEN_OFFICE determine the image, published port, or build arguments before the container starts. Merely putting them in the service's .env.local file does not override those settings. From docker/, provide them in the shell environment, for example:

RAVEN_IMAGE=raven:local RAVEN_WEB_PORT=18893 docker compose up --build

Alternatively, after creating .env.local, explicitly load it for interpolation as well:

docker compose --env-file .env --env-file .env.local up --build

The later file overrides the earlier one for interpolation; shell environment values take precedence over both files.

Persistent data

Raven stores configuration, workspace files, sessions, logs, and memory under /data in the raven-data volume. Removing the container keeps this volume. The command below deletes the volume and all data in it:

docker compose down -v

Run a CLI command

Arguments other than run and signin are passed to the Raven CLI:

docker compose exec raven docker-entrypoint.sh provider test anthropic
docker compose run --rm raven status

Deployment limits

• The default Compose page grants a browser session to anyone who can reach the published port. Keep the default binding on 127.0.0.1, or set RAVEN_AUTO_LOGIN=0 and add a proxy with its own access control before exposing the service remotely.
• The image does not terminate TLS. Use an HTTPS reverse proxy in front of the container for remote deployments.
• The TUI is not built into the image. raven tui needs the bundle from ui-tui/.
• The sandbox extra is disabled by default; commands run within the container. Include it through RAVEN_EXTRAS if you also need Boxlite.
• LibreOffice is included for office-file previews. Build with RAVEN_OFFICE=0 if your deployment does not need office-file previews.