Docker Setup

Selu runs as a set of Docker containers, making it easy to deploy on any machine that supports Docker. This guide walks you through the architecture and setup.

Architecture overview

A Selu deployment consists of the main Selu server container and on-demand agent containers:

selu

The core application server. Handles the dashboard, message routing, local SQLite data, and orchestration.

Agent containers

Each installed agent runs in its own container. These are created automatically when you install agents from the marketplace.

All containers communicate over an internal Docker network. Agent containers connect to the server via gRPC.

Prerequisites

• Docker Engine 29.2 or later — Selu uses Docker Engine API 1.53, which requires this version or newer
• Docker Compose version 2.20 or later
• At least 2 GB of RAM (more if you plan to run many agents or use Ollama locally)
• A Linux, macOS, or Windows machine

Caution

Docker Engine 29.2 or newer is required. Earlier versions won’t work with the current Selu images. Run docker version to check what you have before installing or updating.

Quick start

1. Create a directory for your Selu installation:

mkdir selu && cd selu

2. Run the installer:

bash <(curl -fsSL https://selu.bot/install.sh)

3. Or run non-interactively with your preferred channel:

bash <(curl -fsSL https://selu.bot/install.sh) --yes --channel stable

Open http://localhost:3000 in your browser to access the Selu dashboard.

Docker Compose file

The default docker-compose.yml looks like this:

services:
  selu:
    image: ghcr.io/selu-bot/selu:${SELU_IMAGE_TAG:-stable}
    ports:
      - "${SELU__SERVER__PORT:-3000}:${SELU__SERVER__PORT:-3000}"
    environment:
      - SELU__ENCRYPTION_KEY=${SELU__ENCRYPTION_KEY}
      - SELU__SERVER__HOST=0.0.0.0
      - SELU__SERVER__PORT=${SELU__SERVER__PORT:-3000}
      - SELU__DATABASE__URL=sqlite:///app/data/selu.db?mode=rwc
      - SELU__MARKETPLACE_URL=https://selu.bot/api/marketplace/agents
      - SELU__INSTALLED_AGENTS_DIR=/app/installed_agents
      - SELU__RELEASE_METADATA_URL=https://selu.bot/api/releases/selu
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - selu-data:/app/data
      - ./installed_agents:/app/installed_agents

volumes:
  selu-data:
    external: true
    name: ${SELU_DATA_VOLUME}

Note

The Docker socket mount (/var/run/docker.sock) allows Selu to manage agent containers. This is required for installing and running agents.

Existing installations

Older installations stored Selu data in ./data. To migrate, open that installation directory and rerun the installer. It stops Selu and the updater, copies the complete data directory into a new managed volume, verifies the database copy, and only then switches Docker Compose. Your old ./data directory remains as an inactive fallback copy.

bash <(curl -fsSL https://selu.bot/install.sh)

This is a one-time installer migration. A normal update from the Selu dashboard doesn’t rewrite your storage configuration.

Capability image recovery

If Docker no longer has a cached image for an installed agent’s capability — for example after clearing Docker’s image cache or moving Selu to a new host — Selu recovers automatically:

• On next use: Selu downloads the missing image in the background and then starts the capability as normal. You won’t see an error; there may just be a short delay on that first use.
• Concurrent requests: If multiple requests arrive at the same time for a missing image, Selu shares one download rather than starting several in parallel.

You can also restore missing images proactively without waiting for a user to trigger it:

1. Open the agent’s detail page and go to Overview.
2. Each capability card shows an image status badge:
   • Files ready — the image is present and the capability can start immediately
   • Download needed — the image is missing; Selu will fetch it on next use
   • Status unavailable — Selu couldn’t determine the image status
3. If a capability shows Download needed, click Download now to fetch the image in the background right away.

Tip

After migrating Selu to a new host or pruning Docker images, visit the Overview page for each agent and use Download now on any capabilities showing Download needed. This warms up the cache before users start chatting, so the first response won’t have an unexpected delay.

Updates and rollback

• Open System Updates in the Selu UI.
• Choose a channel (stable, dev, nightly).
• Click Check now and Update now, or enable Auto-update.
• If a release fails health checks, use Rollback to restore the previous version.

Selu verifies release digests from https://selu.bot/api/releases/selu before applying updates. Updates are applied by the selu-updater sidecar container, so update jobs continue even while Selu is being restarted. By default, the sidecar does not refresh itself in the same run. It applies its own image refresh on the next update cycle.

Securing your deployment

• Keep SELU__ENCRYPTION_KEY secret. This key protects encrypted credentials at rest.
• Don’t expose port 3000 directly to the internet. Put a reverse proxy (like Nginx or Caddy) in front with HTTPS.
• Back up your data regularly. Archive the Docker volume named by SELU_DATA_VOLUME in .env, along with .env, docker-compose.yml, and installed_agents.
• Restrict Docker socket access if running in a shared environment.

See the Environment Variables reference for all available configuration options.