Docker

• Run Stelle with a single command.
• The bundled docker-compose.yml brings up MongoDB and Redis for you — you only bring your Lavalink node.

⚙️ Prerequisites

• Docker with Compose v2 (docker compose, not the old docker-compose).
• A Lavalink node reachable from the container (see the note below).

📋 1. Configure the bot

Docker only provides the secrets and the databases via environment variables. Everything else (your Lavalink node, channel ids, developer ids, colors…) still lives in the config file, which is compiled into the image at build time.

1. Create/edit your local.config.ts (or default.config.ts) in /src/config/ as usual.
2. Set your Lavalink nodes there.

Important

Inside a container, localhost is the container itself, not your host machine. If your Lavalink runs on the same host, set the node host to one of:

• host.docker.internal (Docker Desktop on Windows/macOS),
• your host's LAN IP,
• or a public node.

Also make sure the node port/password in the config match your Lavalink.

📋 2. Create the .env

Next to docker-compose.yml, create a .env with your secrets. MongoDB and Redis are provided by Compose, so you only need:

TOKEN="your-discord-token"
ERRORS_WEBHOOK="your-error-webhook-url"

# Optional: password for the bundled Redis (defaults to "stelle")
# REDIS_PASSWORD="change-me"

Note

DATABASE_URL and the REDIS_* host/port are set by Compose to point at the bundled services — you don't need them in .env.

📋 3. Run it

docker compose up -d --build

That's it. This builds the bot image and starts three containers:

Service	Image	Purpose
stelle-bot	built from the Dockerfile	The bot.
stelle-mongo	mongo:7	Database (single-node replica set, required by Prisma).
stelle-redis	redis:7-alpine	Queue store / cache.

The bot waits until Mongo and Redis are healthy before starting.

🔧 Managing

# Follow the logs
docker compose logs -f bot

# Stop everything
docker compose down

# Stop AND wipe the database/cache volumes
docker compose down -v

# Apply code or config changes (rebuild the image)
docker compose up -d --build

Tip

Config and code are baked into the image, so after changing them re-run with --build.

🧠 How it works

• MongoDB replica set — Prisma requires MongoDB to run as a replica set. The mongo service starts with --replSet rs0 and a healthcheck initiates the set on first run.
• Data persistence — sessions (24/7, resume), rendered banners, and the databases live in named volumes (stelle-cache, stelle-logs, mongo-data, redis-data), so they survive restarts. Named volumes (not bind mounts) also let the non-root bot user write to them.
• Multi-stage build — dependencies are installed and the app is compiled in a builder stage; the final image only ships the compiled dist/, production node_modules, assets/ (banner fonts), and the Prisma query engine.
• Non-root — the bot runs as an unprivileged user.

Note

MongoDB works out of the box, but the @unique indexes are only created by prisma db push. If you want them enforced, run pnpm db:push once against your DATABASE_URL (optional for a personal bot).

🩺 Troubleshooting

Symptom	Likely cause
Bot logs ECONNREFUSED to Lavalink	Node host is localhost (points at the container) or wrong port/password — see step 1.
TOKEN/ERRORS_WEBHOOK error on start	Missing from .env.
Mongo unhealthy / bot never starts	Give it a few seconds on first run — the replica set is initializing (start_period).
Redis auth errors	REDIS_PASSWORD in .env must match what the bot uses (Compose keeps them in sync).