Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/onesoft-sudo/sudobot/llms.txt

Use this file to discover all available pages before exploring further.

Docker lets you run SudoBot and its PostgreSQL database together in isolated containers without installing Node.js, Bun, or database software directly on your host. The SudoBot repository includes a multi-stage Dockerfile and a docker-compose.yml that manage both the bot and the database as a single stack.
Using Docker also makes SudoBot portable — you can run it on any platform that supports Docker, including Windows, macOS, and Linux.

​
Prerequisites

Install the following tools before you begin:

​
Setup steps

1

Clone the repository

Clone the SudoBot repository to your local machine:
git clone https://github.com/onesoft-sudo/sudobot
cd sudobot
2

Configure environment variables

Create a .env.docker file in the project root. Docker Compose mounts this file into the container as /app/.env at runtime.
DB_URL=postgresql://postgres:root@postgres:5432/sudobot
SUDO_PREFIX=/app/storage

# Add your bot token and other required variables below.
# TOKEN=your-bot-token
# CLIENT_ID=your-bot-client-id
# CLIENT_SECRET=your-bot-client-secret
# HOME_GUILD_ID=your-home-guild-id
# JWT_SECRET=your-jwt-secret
The DB_URL uses postgres as the hostname because that is the service name defined in docker-compose.yml — Docker’s internal DNS resolves it to the database container automatically. Do not change it to localhost.
For the full list of supported environment variables, see the environment variables reference or the EnvironmentVariableSchema source file.
3

Set up the storage directory

Create a storage/ directory in the project root and copy the default config files into it:
mkdir -p storage
cp -r config storage/config
Docker Compose mounts ./storage to /app/storage inside the container. Keeping config files here ensures they persist across container rebuilds and are not overwritten by updates.Edit storage/config/config.json and storage/config/system.json to match your server settings before starting the bot.
4

Build and start the containers

Start the full stack — SudoBot, PostgreSQL, and Adminer — with Docker Compose:
docker-compose up -d
The -d flag runs the containers in the background (detached mode). Remove it if you want to stream logs directly to your terminal:
docker-compose up
On first run, Docker will build the SudoBot image using the multi-stage Dockerfile. This may take several minutes. Subsequent starts are faster because Docker caches the build layers.
The database migration runs automatically on container startup if it has not been applied yet. SudoBot checks for a .migration_status file before deciding whether to run migrations.

​
What the Compose stack includes

The docker-compose.yml defines three services:
ServiceDescription
sudobotThe bot itself, built from the local Dockerfile. Exposes port 4000 for the REST API.
postgresPostgreSQL 16 (Alpine). Data is persisted in a named Docker volume (pgdata).
adminerA lightweight database UI accessible at http://localhost:8080. Useful for inspecting the database.

​
Managing the containers

# View running containers
docker-compose ps

# Stream logs from the bot
docker-compose logs -f sudobot

# Stop all containers
docker-compose down

# Stop and remove volumes (deletes database data)
docker-compose down -v

# Rebuild the bot image after a code change
docker-compose build sudobot
docker-compose up -d

​
Customizing the setup

The Dockerfile and docker-compose.yml are included in the repository and are yours to modify. Common customizations include:
  • Changing the PostgreSQL credentials — update both the postgres service environment block and DB_URL in .env.docker.
  • Removing the adminer service from docker-compose.yml if you don’t need it.
  • Adding a reverse proxy service (such as Nginx) to the Compose stack to expose the REST API securely.
  • Pinning the postgres image to a different version.
If you change the POSTGRES_USER, POSTGRES_PASSWORD, or POSTGRES_DB values in the Compose file, update the DB_URL in .env.docker to match. Mismatched credentials will prevent the bot from connecting to the database.

Build docs developers (and LLMs) love

Get started for freeTalk to us