Docker
Building the Modbot image from the repository and running it next to PostgreSQL and Seq with docker run or Docker Compose.
Modbot is one container plus a PostgreSQL database. Pull the published image, or build it yourself
from the Dockerfile at the root of the repository, then run it with DATABASE_URL pointing at
your database.
This page is the long way round, and every step of it is yours to change. The install script does the same thing in one command if you would rather not.
What the image needs
DATABASE_URL | Required. Where the database is, as postgres://user:password@host:5432/database or a keyword connection string. See PostgreSQL. |
PORT | Optional. The port Modbot listens on inside the container. Defaults to 8080. |
Port 8080 | Publish it (or whatever you set PORT to) so you can reach the web app. |
/app/logs | Where log files are written. Mount a volume here if you want to keep them when the container is replaced. |
/health/live | Answers while the process is running. The image's own Docker health check uses it. |
/health/ready | Answers healthy only when Modbot can reach its database. |
Every other setting is entered in the web app and stored in the database. See Environment variables for the few optional ones.
Run one Modbot container per database. Modbot holds one VRChat session and paces its own requests, and a second container would send twice as many against the same rate limit.
Pull the published image
Every named release is published to GitHub's container registry as
ghcr.io/modbot/modbot:
| Tag | What it is |
|---|---|
latest | The newest release. This is the one to run a group on. |
latest-preview | The newest preview: a build handed out for testing before it is released. Try it on a spare Modbot, not on the one your group depends on. latest never points at a preview. |
v2026.9.1 | One release, by its version. A preview version has -preview.1 on the end, as in v2026.9.3-preview.1. |
edge | The newest commit on master, ahead of any release. |
sha-1af5e1a | One commit. |
docker pull ghcr.io/modbot/modbot:latestEvery tag serves both linux/amd64 and linux/arm64, so docker pull gets a working image on an
Intel or AMD machine, on an Apple Silicon Mac, on an arm64 server and on a Raspberry Pi alike. For a
Pi, see Small machines.
While the image is private, sign in first with a GitHub token that has the read:packages scope:
echo "$GITHUB_TOKEN" | docker login ghcr.io -u your-github-username --password-stdinWherever the rest of this page says modbot, the published image is ghcr.io/modbot/modbot
with the tag you chose.
Build the image
The build needs the whole repository, because the image contains both the server and the web app. Run this from the root of a copy of the repository:
git clone https://github.com/Modbot/Modbot.git
cd Modbot
docker build -t modbot .The This install card in Settings shows the commit and branch the image was built from
(point at Version), if the build is told. A plain docker build has no access to git, so pass
them in if you want them shown:
docker build -t modbot \
--build-arg RAILWAY_GIT_COMMIT_SHA="$(git rev-parse HEAD)" \
--build-arg RAILWAY_GIT_BRANCH="$(git rev-parse --abbrev-ref HEAD)" \
.The build arguments have Railway in their names because Railway sets them automatically. They work the same anywhere.
Run it with docker run
This creates a private network, a PostgreSQL 16 database with its own volume, and Modbot:
docker network create modbot
docker run -d --name modbot-db --network modbot \
-e POSTGRES_USER=modbot \
-e POSTGRES_PASSWORD=choose-a-long-password \
-e POSTGRES_DB=modbot \
-v modbot-db:/var/lib/postgresql/data \
--restart unless-stopped \
postgres:16-alpine
docker run -d --name modbot --network modbot \
-e DATABASE_URL=postgres://modbot:choose-a-long-password@modbot-db:5432/modbot \
-p 8080:8080 \
-v modbot-logs:/app/logs \
-v modbot-data:/app/data \
--restart unless-stopped \
modbotModbot can start before the database is ready. It tries to connect up to 10 times, 3 seconds apart, before giving up.
Run it with Docker Compose
The repository ships docker-compose.yml in its root. It runs Modbot, PostgreSQL 16 and
Seq together, with a volume for each:
| Service | Volume | Holds |
|---|---|---|
modbot | modbot-logs → /app/logs | Log files |
modbot | modbot-data → /app/data | Evidence, when it is stored on disk (/app/data/evidence) |
postgres | postgres-data | The database |
seq | seq-data | Seq's stored logs and settings |
Copy .env.example to .env, set POSTGRES_PASSWORD and SEQ_ADMIN_PASSWORD, then start it:
cp .env.example .env
docker compose up -d --build- Modbot waits until the database is ready before starting.
- Modbot is at
http://localhost:8080, from the same computer only, like Seq. To publish it on a different port, setMODBOT_PORTin.env. A reverse proxy running on the same computer reaches it as it is. To open it to other computers, which a proxy in its own container or on another machine needs, setMODBOT_BIND=0.0.0.0in.env. - Seq is at
http://localhost:5380, reachable from the same computer only. Sign in asadminwithSEQ_ADMIN_PASSWORD. Seq reads it only the first time it starts with an empty volume. Modbot sends its logs to Seq over the Compose network. - The database connection uses the keyword form, so the password needs no escaping, but it must not
contain
;. .envalso takes these optional settings:MODBOT_DEBUG_LOGGINGCONSOLE_LOG_MODEandLOG_LEVEL, covered in Console log modesMODBOT_CLOUD_ENDPOINTMODBOT_CLOUD_DISABLEDMODBOT_DEMOandMODBOT_DEMO_RESET_HOURS, to run this Modbot as a public demoMODBOT_SETUP_CODE, to choose the setup code yourselfMODBOT_COMMITandMODBOT_BRANCH, to show the version commit and release branch in Settings
Open it
Open http://localhost:8080 on the same computer. A new Modbot sends you to the
setup wizard, whose first step asks for the
setup code Modbot prints to its log:
docker compose logs modbot | grep "Setup code" # Docker Compose
docker logs modbot | grep "Setup code" # docker runUse HTTPS from anywhere but localhost
Modbot's sign-in cookie is marked secure, so browsers only keep it over HTTPS. Browsers make an
exception for localhost. To reach Modbot from any other address, put a reverse proxy that
provides HTTPS in front of it. The proxy must also pass WebSocket connections through if you use
live events over WebSocket.
Logs
The container prints its log to the console, so docker logs modbot shows it. It also writes log
files to /app/logs. With the volume above, those files survive when the container is replaced.
See Checking a deployment.
Keeping evidence on disk
If you choose A directory on disk for evidence under Settings, Evidence, the default
directory is /app/data/evidence. Mount a volume there, or the files are lost when the container is
replaced.
Add -v modbot-data:/app/data to the docker run command for Modbot; the Compose file already
mounts it. The image creates /app/data owned by the container's user, so a new named volume there
can be written to straight away.
A volume created by an older image, or a host folder mounted instead, may belong to root. If Test and save says the directory cannot be written, give it to the container's user:
docker run --rm -v modbot-data:/data alpine \
chown -R "$(docker run --rm --entrypoint id modbot -u)":0 /dataThen recreate the container. See Storage buckets for the other choices.
Railway
Deploying Modbot on Railway as one service plus one Postgres database, with the health check, variables and optional bucket.
Small machines
Running Modbot on a Raspberry Pi or a small VPS — what the machine needs, what to change on the database, and the memory and startup times measured on four cores.