Modbot Docs
Self-hosting

Railway

Deploying Modbot on Railway as one service plus one Postgres database, with the health check, variables and optional bucket.

On Railway, Modbot is one service plus one Postgres database. The service is built from the Dockerfile at the root of the repository, and its only required variable, DATABASE_URL, points at the database. Railway supplies PORT itself.

Deploy on Railway

The button above deploys the template, which creates the service and the Postgres database with the health check and the variables already set. You can also create the project from the configuration file in the repository, or set it up by hand in the Railway dashboard. All three end with the same result.

What the project looks like

The repository describes the Railway project in .railway/railway.ts:

ValueWhy
DatabaseOne Postgres, named postgresHolds everything Modbot knows and every setting.
ServiceOne service, named modbotThe server, the web app, the sync and the Discord bot.
DATABASE_URLTaken from the Postgres databaseThe only variable you must set.
Health check path/health/readyA new deployment only counts as healthy once it has updated the database and can reach it.
Health check timeout300 secondsA first deploy updates a database that may have only just been created. A short timeout would fail a deploy that was only slow.
Replicas1Modbot holds one VRChat session and paces its own requests. A second copy would double the requests against the same rate limit.

Keep it at one replica

Do not scale the Modbot service beyond one replica.

Option 1: from the repository's configuration file

The .railway/README.md file in the repository gives these commands. Run them from a copy of the repository:

npm install railway     # the Railway configuration library, needed to read railway.ts
railway login && railway link
railway config plan     # preview what will be created
railway config apply    # create it, after you confirm

Railway creates the database and the service, and wires DATABASE_URL between them.

The repository has no railway.json. Railway has deprecated that format, so the configuration lives only in railway.ts.

Option 2: by hand in the dashboard

Create the service

Create a new Railway project and deploy it from the Modbot GitHub repository, or from your own fork. Leave the root directory empty. Railway finds the Dockerfile at the root and builds it.

Add PostgreSQL

Add a PostgreSQL database to the same project.

Point Modbot at the database

In the Modbot service's variables, add DATABASE_URL and set it to the Postgres database's own DATABASE_URL, using a Railway reference variable. If your database service is called Postgres, that is:

DATABASE_URL=${{Postgres.DATABASE_URL}}

Do not set PORT. Railway sets it.

Set the health check

In the Modbot service's settings, set the health check path to /health/ready and the timeout to 300 seconds. Keep the service at one replica.

Give it an address

Generate a public domain for the Modbot service, then open it. You land in the setup wizard.

Find the setup code

The wizard's first step asks for a setup code. Open the deployment's logs and search for Setup code. The address is public from the moment Railway gives it out, and the code is what stops a stranger who finds it first from creating the administrator account. To choose the code yourself, set MODBOT_SETUP_CODE on the service.

What Modbot reads from Railway

Railway sets some variables on every service. Modbot reads a few of them, and none of them needs anything from you.

VariableWhat Modbot does with it
PORTListens on it.
RAILWAY_PUBLIC_DOMAINSuggests it as your Modbot's public address in the setup wizard and in Settings, Server, Public address. You still confirm it; links sent by email or Discord are only built from the address you save.
RAILWAY_GIT_COMMIT_SHA, RAILWAY_GIT_BRANCHShown when you point at Version on the This install card. The Dockerfile declares them, so Railway passes them to the build.
RAILWAY_ENVIRONMENT, RAILWAY_PROJECT_ID, RAILWAY_SERVICE_IDShow Install as Railway on the This install card.

Adding a bucket for evidence

Evidence storage is optional, but on Railway a bucket is the simplest place to keep evidence files. When you add a Railway bucket to the Modbot service, Railway sets BUCKET, ENDPOINT, ACCESS_KEY_ID, SECRET_ACCESS_KEY and REGION on it.

Modbot uses those only to fill in the form under Settings, Evidence, Where evidence is stored, while no storage has been chosen yet. You still press Test and save. After that, Modbot ignores the variables, so changing them later does not move your evidence.

Railway's bucket credentials page tells you whether the bucket uses path-style addresses. If it does, tick Path-style URLs before you save.

See Storage buckets for the whole form and what the test does.

Logs on Railway

Railway throws away a container's disk when it redeploys, unless you mount a volume. Modbot still writes its log files to /app/logs, and warns at startup that they will not survive unless a volume is mounted there. Railway keeps what Modbot prints to its console, which you can read in the deployment's logs.

Set CONSOLE_LOG_MODE=railway_json on the service. Modbot then prints one JSON object per line in the shape Railway parses: the level colours the line, the message is the text, and everything else becomes an attribute you can filter on, such as @StatusCode:500 or @logLevel:Fatal. See Console log modes.

To keep full logs across deploys, do one of these:

  • set SEQ_URL to a Seq server, or
  • mount a Railway volume at /app/logs.

Modbot notices a mounted volume by itself after the next restart. See Checking a deployment for the log files and what the Log files row means.

Catching a crash that leaves no log

If the service restarts on its own and the log stops mid-sentence with no error, the process died in a way no log line survives. .NET can write a dump of the whole process at that moment instead.

  1. Mount a Railway volume at /app/data. Without one the dump is thrown away with the container.
  2. Set these on the service:
DOTNET_DbgEnableMiniDump=1
DOTNET_DbgMiniDumpType=2
DOTNET_DbgMiniDumpName=/app/data/dumps/modbot.%p.dmp
  1. Redeploy. The startup log then says Crash dumps are on and go to …, and Modbot makes the folder for them.

After the next crash the file is under /app/data/dumps. Open it with dotnet-dump: dotnet-dump analyze modbot.1.dmp, then clrstack -all.

DOTNET_DbgMiniDumpType=2 writes the managed heap with the dump, so it is roughly the size of the memory the service was using. Turn the variables off again once you have one.

Common problems

The deploy log says DATABASE_URL is not set. The variable is missing or empty on the Modbot service. Add it as a reference to the Postgres database, as above.

The deploy waits, then fails its health check. On the very first deploy Modbot waits for the database to accept connections (up to 10 tries, 3 seconds apart), then creates its tables, and it only starts answering health checks after that. Check that the timeout is 300 seconds and read the deploy log: every database problem is written as one sentence naming what is wrong, such as a rejected password or a database that does not exist.

The connection check in the setup wizard says Cloudflare is blocking this network. Your host's network cannot reach VRChat. Add a proxy on that step. See the setup wizard.

Modbot is not endorsed by or affiliated with VRChat Inc. or Discord Inc. VRChat is a trademark of VRChat Inc. Discord is a trademark of Discord Inc. SteamVR is a trademark of Valve Corporation. Windows is a trademark of Microsoft Corporation. Docker is a trademark of Docker, Inc. PostgreSQL is a trademark of the PostgreSQL Community Association of Canada. Railway is a trademark of Railway Corp. Other names are trademarks of their respective owners; see Legal. Modbot and its logo are trademarks of the Modbot project. Open source under AGPL-3.0.

On this page