Docker Compose setup and step-by-step instructions for running your own MaintMode instance.
MaintMode is a maintenance calendar for engineering teams. Several teams share the same infrastructure; two changes touch the same database in overlapping windows and nobody notices until something breaks. MaintMode makes that visible beforehand:
- One calendar of planned technical work — week and month views
- Planned window vs. actual execution time, tracked separately
- Shared resources: services, databases, clusters
- Conflict detection when work overlaps on the same resource
- Approval flows for changes that need sign-off
- Notifications to Slack, Telegram, and email
- Role-based access control and invitation-based user management
- Audit log
Self-hosting is free and unlimited. No seat counting, no licence check, no phoning home. See Licensing and telemetry for what that means concretely in the code.
Source repositories:
- Backend (Go) — maintmode-dev/maintmode
- Frontend (Next.js) — maintmode-dev/maintmode-ui
Both are AGPL-3.0, as is this repository.
ghcr.io/maintmode-dev/maintmode:${MAINTMODE_VERSION}
ghcr.io/maintmode-dev/maintmode-ui:${MAINTMODE_UI_VERSION}
ghcr.io/maintmode-dev/maintmode-migrations:${MAINTMODE_VERSION}
Published to GHCR for linux/amd64 and linux/arm64, so an Apple Silicon Mac
runs them natively. They are public — no docker login needed.
The version comes from MAINTMODE_VERSION / MAINTMODE_UI_VERSION in your
.env. CI tags every build three ways: by release tag (v0.1.0), by branch
(main) and by commit (sha-abc1234). Pin a release tag in production —
main moves whenever you happen to run docker compose pull, which is rarely
what you want. Keep maintmode and maintmode-migrations on the same version:
they ship as a pair, and the migrations image carries exactly the schema that
backend build expects.
- Docker Engine 20.10+ with Compose v2. Check with
docker compose version(a space, not a hyphen). Docker Desktop on macOS and Windows includes it. - RAM: 2 GB is enough for a small team. Postgres and the two application containers idle at roughly 700 MB together; the rest is headroom for the Next.js server under load. 4 GB is comfortable.
- Disk: 5 GB for images and a young database. Growth is driven almost entirely by the audit log, which is pruned to 365 days by default.
- A Google account with access to Google Cloud Console. Google is the sign-in method this guide sets up for your users.
- An SMTP server the backend can reach. The instance is invite-only and
invitations go out by email; you enter the server in the admin UI after the
first login. The same transport enables sign-in by emailed code. A relay on
your internal network (a private address, or a name resolving to one) is
refused until you set
notify_transport.allow_internal_hosts: trueinconfig/app.config.yaml. - An HTTPS URL on a real domain, if this is going to be used by anyone
other than you. See Behind a reverse proxy with TLS
and Does it have to be on the internet?
Plain HTTP works only at
localhost: several sign-in cookies are markedSecure, and browsers drop those over HTTP anywhere else. On, say,http://10.0.0.5:3000, sign-in by emailed code, password reset and Google sign-in fail, and signed-in users are logged out unpredictably when their session refreshes.
| Port | Where | Purpose |
|---|---|---|
| 3000 | published on the host | The gateway: the web interface, plus the two backend routes of Google sign-in. This is the only port published, and it binds to 127.0.0.1 by default. Change with MAINTMODE_HTTP_PORT. |
| 8000 | compose network only | Backend API. Called by the frontend server. A browser reaches only /auth/api/v1/login/oauth/{provider}/start and /callback, through the gateway; every other backend route stays internal. |
| 8001 | compose network only | Backend health and readiness. Never published, not even through the gateway. |
| 5432 | compose network only | Postgres. Deliberately not published. |
| 6379 | compose network only | Valkey. Deliberately not published, and password-protected. |
Only port 3000 needs to be free on your host.
Do this first. It is the step most installs stall on.
You need two values — a client ID and a client secret — and you need to register one exact redirect URI.
How sign-in works, because it explains every value below: the "Sign in with Google" button sends the browser to your instance's backend, which redirects it to Google; Google sends the browser back to the backend's callback, and the backend exchanges the code with Google directly, using the client secret. The backend is a confidential client: the secret lives on your server, never in a browser.
Open Google Cloud Console and create a project (or select an existing one). The project is just a container; nothing about it is billed for OAuth.
Under APIs & Services → OAuth consent screen:
- User type: choose Internal if your Google Workspace organisation is the only group that will use MaintMode — it restricts sign-in to your own domain, which is a useful extra fence. Choose External otherwise.
- Fill in the app name, a support email, and a developer contact email. These are shown to users on the Google consent screen.
- Scopes: the defaults are enough. MaintMode reads only the basic profile — email, name, and the stable Google account identifier. It never requests access to Gmail, Drive, or Calendar.
- If you chose External and leave the app in Testing, only accounts you add as test users can sign in, and their consent expires after seven days. For anything beyond a trial, publish the app.
Under APIs & Services → Credentials → Create Credentials → OAuth client ID:
-
Application type: Web application. Not "Desktop app", not "TVs and limited-input devices" — those client types cannot use the redirect flow and produce confusing failures later.
-
Give it a name (only you see it).
-
Authorized redirect URIs → Add URI. This is the part that matters:
<MAINTMODE_APP_BASE_URL>/auth/api/v1/login/oauth/google/callbackSubstituting the URL your users will actually type. For a local trial:
http://localhost:3000/auth/api/v1/login/oauth/google/callbackBehind TLS on your own domain:
https://maintmode.example.com/auth/api/v1/login/oauth/google/callbackIt must match exactly — scheme, host, port, and path.
httpvshttps, a trailing slash,localhostvs127.0.0.1, and a missing port are all mismatches. Google compares the string, not the destination.Note the
/authprefix. The backend itself serves/api/v1/login/oauth/...; the gateway puts it under/authand strips the prefix on the way in. Google and the browser see the external form, with/auth, and that is the one you register. Registering the internal form fails withredirect_uri_mismatchon Google's side, which never reaches MaintMode's logs.You may register several URIs on one client, which is handy if you want to test locally and run in production against the same client.
-
Authorized JavaScript origins can be left empty. MaintMode's login is a server-side redirect flow; nothing calls Google from browser JavaScript.
Google shows a Client ID (ends in .apps.googleusercontent.com) and a
Client secret. Both go to the backend:
- the client ID into
config/app.config.yaml, atoauth_providers.providers.google.client_id; - the client secret into
config/app.secrets.yaml, underauth_provider/google/client_secret. The config file only references it (<secret:auth_provider/google/client_secret>); never paste the secret into the config file itself.
The client ID is not sensitive — it travels in every browser redirect. The client secret is: it stays on your server and is never sent to a browser.
git clone https://github.com/maintmode-dev/maintmode-selfhost.git
cd maintmode-selfhostcp .env.example .envEight random values. Run each command and keep the output — you will paste them in the next two steps.
# Database password
openssl rand -hex 32
# Valkey password
openssl rand -hex 32
# Frontend session secret (MAINTMODE_AUTH_SECRET)
openssl rand -hex 32
# Frontend credential (MAINTMODE_BACKEND_S2S_TOKEN and s2s/maintmode-ui/secret)
openssl rand -hex 32
# Backend token signing key (jwt/issuer_private_key)
openssl rand -hex 32
# Encryption master key (crypto/kek/selfhost-1)
openssl rand -hex 32
# Signing key ID (jwt/issuer_kid) — shorter
openssl rand -hex 16
# Break-glass password (bootstrap/password) — you will type this one
openssl rand -base64 24Generate each one separately; do not reuse a single value across them. The
frontend credential, like the database and Valkey passwords, goes into both
.env and config/app.secrets.yaml.
A note on the signing key: it is a raw 32-byte P-256 scalar, hex-encoded, so
openssl rand -hex 32 is exactly right. Do not use
openssl ecparam -genkey ... | xxd — that produces a DER structure rather than
a raw scalar, and the backend rejects it at startup. The backend also rejects a
key made of one repeated byte, so a placeholder fails loudly instead of quietly
becoming a guessable signing key.
Open .env and set:
| Variable | Value |
|---|---|
POSTGRES_PASSWORD |
the database password you generated |
VALKEY_PASSWORD |
the Valkey password you generated |
MAINTMODE_AUTH_SECRET |
the session secret (min 32 chars) |
MAINTMODE_BACKEND_S2S_TOKEN |
the frontend credential (min 32 chars) |
MAINTMODE_APP_BASE_URL |
the URL users will type, no trailing slash |
MAINTMODE_APP_BASE_URL must be the start of the redirect URI you registered
with Google. If you registered
http://localhost:3000/auth/api/v1/login/oauth/google/callback, this is
http://localhost:3000.
cp config/app.secrets.example.yaml config/app.secrets.yaml
chmod 644 config/app.secrets.yamlOpen it and replace every REPLACE_ME:
| Key | Value |
|---|---|
db/dsn |
the same database password as POSTGRES_PASSWORD, inside the connection string |
valkey/password |
the same Valkey password as VALKEY_PASSWORD |
auth_provider/google/client_secret |
the Client secret from Google Cloud Console |
jwt/issuer_private_key |
the 64-hex-char signing key |
jwt/issuer_kid |
the 32-hex-char key ID |
crypto/kek/selfhost-1 |
the 64-hex-char encryption key |
bootstrap/password |
the break-glass password (at least 20 characters) |
s2s/maintmode-ui/secret |
the frontend credential — the same value as MAINTMODE_BACKEND_S2S_TOKEN |
The database password appears in both files and must match exactly; a mismatch fails at startup with an authentication error.
Keep the break-glass password somewhere safe — a password manager, not this host only. On a fresh instance it is the only way to sign in as the first administrator.
The chmod 644 matters: the backend container runs as an unprivileged user and
cannot read a 600 file owned by you.
config/app.config.yaml needs three edits; everything else works unchanged:
| Key | Value |
|---|---|
app.frontend_url |
the same value as MAINTMODE_APP_BASE_URL |
oauth_providers.providers.google.client_id |
the Client ID from Google Cloud Console |
oauth_providers.providers.google.redirect_uri |
exactly the redirect URI you registered with Google |
app.frontend_url is where the backend sends a browser at the end of sign-in;
a stale value drops users somewhere unexpected after an otherwise working
login. Leave app.oauth_callback_path and app.oauth_cookie_path as they are:
they are fixed by the frontend and the gateway.
docker compose up -dWatch it come up:
docker compose ps
docker compose logs -fThe order is enforced by health checks: Postgres and Valkey become healthy, the migration job runs to completion and exits, the backend starts and reports ready, then the frontend starts and reports healthy, and only then the gateway starts. First start takes a minute or two.
Then read the next section before you do anything else.
A fresh instance is invite-only and has no users, so nobody can sign in with
Google yet — an unknown account without an invitation is refused. The first
administrator is the break-glass account, which signs in with the
bootstrap/password from config/app.secrets.yaml and nothing else.
- Open
<MAINTMODE_APP_BASE_URL>/login/recovery— for a local trial, http://localhost:3000/login/recovery. - Enter the break-glass password. You are now signed in as the break-glass administrator.
- In the admin UI, set up the email integration (your SMTP server).
Invitations are delivered only by email. If the test email fails for a
relay on your internal network, see
allow_internal_hostsinconfig/app.config.yaml; after changing it, rundocker compose restart maintmode. - Set up Slack or Telegram under Administration → Integrations, then create at least one notification channel under Channels. Every maintenance must notify at least one channel, so until one exists nobody can create a maintenance. Email does not count: it delivers invitations and sign-in codes only, and a channel cannot be created on it.
- Invite yourself — your own Google address — with the admin role, and invite your colleagues.
- Sign out, open the link from your invitation email, and sign in with Google.
- Only then expose the instance (reverse proxy, or
MAINTMODE_BIND_ADDRESS=0.0.0.0).
compose.yaml binds port 3000 to 127.0.0.1 by default, so a fresh
docker compose up is not exposed to your network until you deliberately
change that.
Keep the break-glass password afterwards. It is the way back in when the usual
sign-in methods are turned off or broken — a revoked Google client, say — and
/login/recovery keeps working regardless. Anyone who has it is an
administrator, so treat it like a root password; to retire break-glass
entirely, set bootstrap/password to "" and run
docker compose restart maintmode.
allow_open_signup: false in config/app.config.yaml is what keeps the
instance invite-only. Setting it to true lets any Google account create an
account.
For anything beyond a local trial, put a reverse proxy in front and terminate TLS there. MaintMode does not terminate TLS itself.
Four things must agree, and the login flow breaks if any one of them drifts:
MAINTMODE_APP_BASE_URLin.env— the public HTTPS URLapp.frontend_urlinconfig/app.config.yaml— the same value- The Authorized redirect URI in Google Cloud Console —
<that URL>/auth/api/v1/login/oauth/google/callback oauth_providers.providers.google.redirect_uriinconfig/app.config.yaml— the same string as 3
Note the external form in 3 and 4: with the /auth prefix, as the browser sees
it. Update all four together whenever the public URL changes. The change spans
.env and config/app.config.yaml, so apply it with both commands — up -d
alone leaves the backend on the old URL (see
Applying configuration changes):
docker compose up -d
docker compose restart maintmodeThe proxy sends everything to the gateway on port 3000; the gateway decides
what goes to the backend. Keep the gateway bound to 127.0.0.1 (the default)
when the proxy runs on the same host. The proxy reaches it over loopback;
nothing else can.
Caddy obtains and renews a certificate automatically. The whole config:
maintmode.example.com {
header Strict-Transport-Security "max-age=31536000"
reverse_proxy 127.0.0.1:3000
}Strict-Transport-Security (HSTS) tells browsers to use HTTPS only for this
host from then on, so nobody can downgrade a user to plain HTTP. Neither Caddy
nor MaintMode sends it by default. Add it once HTTPS works: browsers remember it
for the max-age, a year here.
Point your domain's A record at the host first — Caddy needs to answer an ACME challenge on port 80 before it can issue the certificate.
server {
listen 443 ssl;
server_name maintmode.example.com;
ssl_certificate /etc/letsencrypt/live/maintmode.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/maintmode.example.com/privkey.pem;
add_header Strict-Transport-Security "max-age=31536000" always;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_http_version 1.1;
# Conventional; the frontend does not depend on them (it takes its
# public URL from MAINTMODE_APP_BASE_URL), and the gateway replaces
# X-Forwarded-For with the address that connected to it.
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
server {
listen 80;
server_name maintmode.example.com;
return 301 https://$host$request_uri;
}Certificates come from certbot or your own CA; nginx will not obtain them for you the way Caddy does.
Google sign-in puts two backend routes on your public surface. The backend
caps its sign-in routes per client (30 requests a minute,
api_server.rate_limiter), keyed on the address that connected to the gateway.
The gateway trusts no incoming X-Forwarded-For and hands the application
exactly one client address, so a client cannot fake its way into a fresh
budget — but behind your own proxy every client arrives as that proxy and
shares one bucket, unless you trust the proxy's exact address in
gateway/Caddyfile (trusted_proxies static <address>/32; the comment there
explains it). Trust only that address, never private_ranges: trusting your
LAN lets anyone on it choose the address they are limited by. Either way a
per-client limit at your proxy, where the real address is known, stops a flood
before it reaches the application.
Two rules make it work:
- Key on the connection's IP, not on
X-Forwarded-For. A client sets that header to whatever it likes; a limit keyed on it is bypassed by sending a new "address" with every request. - If something sits in front of your proxy (Cloudflare, a cloud load
balancer), every client arrives from that front's address and shares one
bucket. Trust it explicitly and key on the address it reports: in Caddy,
trusted_proxiespluskey {client_ip}instead of{remote_host}; in nginx,set_real_ip_fromplusreal_ip_header X-Forwarded-For(or the front's own header, such asCF-Connecting-IP).
nginx has limit_req built in:
# In the http {} block:
limit_req_zone $binary_remote_addr zone=maintmode_auth:10m rate=10r/s;
# In the server {} block, next to location /:
location /auth/ {
limit_req zone=maintmode_auth burst=100 nodelay;
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}Caddy needs the third-party
rate_limit module, which the
official image does not include. Build Caddy with it
(xcaddy build --with github.com/mholt/caddy-ratelimit), then:
{
order rate_limit before reverse_proxy
}
maintmode.example.com {
rate_limit {
zone maintmode_auth {
match {
path /auth/*
}
key {remote_host}
events 100
window 10s
}
}
reverse_proxy 127.0.0.1:3000
}{remote_host} is the connection's address, not a header. If you would rather
not build Caddy, the backend's shared cap is what remains.
No. Google never connects to your instance: the redirect to the callback is made by the user's browser, so the instance only has to be reachable from your users' browsers, which can be an internal network. What it does need:
- Outbound HTTPS to Google from the backend container (
accounts.google.com,oauth2.googleapis.com,www.googleapis.com), to exchange the code and check the result. - A redirect URI Google accepts. Google requires
httpsunless the host islocalhost, and a domain name rather than an IP address — one ending in a public top-level domain. An internal name likemaintmode.corp.example.comthat only your network resolves works; a bare10.0.0.5or a.localname does not.
If neither is possible, Google sign-in is not for that network. Sign-in by emailed code works without Google, given an email server the backend can reach, and break-glass works anywhere.
Which command applies a change depends on which file you edited:
| You changed | Run |
|---|---|
.env |
docker compose up -d |
config/app.config.yaml or config/app.secrets.yaml |
docker compose restart maintmode |
| Both | docker compose up -d, then docker compose restart maintmode |
up -d recreates a container only when its image or its settings in
compose.yaml change, and values from .env are part of those settings. The
two files under config/ are mounted into the backend container instead:
Compose does not look inside them, so after editing either one up -d
reports every container as running and the backend keeps the configuration it
read at startup. restart makes it read both files again.
up -d also leaves dependent containers alone. When a change in .env
recreates Valkey, say, the backend is not restarted with it — which is why a
change spanning both kinds of file needs both commands.
docker compose pull
docker compose up -dpull fetches new images, up -d recreates only the containers whose image
changed. Expect under a minute of downtime.
Migrations run automatically. The migrations service runs before the
backend on every up, applies any new migrations, and exits. Already-applied
migrations are skipped, so running it repeatedly is safe. If it fails, the
backend does not start at all — deliberately, since a backend running against a
schema it does not expect corrupts data in ways that are far worse than
downtime.
Back up before updating. See below. A schema migration is not reversible by
docker compose down.
Pin your versions. CI tags images by release tag (v1.2.3), by branch
(main) and by commit (sha-abc1234), and points latest at the newest
release. Set MAINTMODE_VERSION to a release tag in production: main and
latest both move whenever you happen to run pull, which is rarely what you
want. Keep the backend and
migrations images on the same version — they ship as a pair, and the migrations
image contains exactly the schema that backend build expects.
Taking a newer config/app.config.yaml? Compare your
config/app.secrets.yaml with config/app.secrets.example.yaml and add any
key you are missing: every <secret:...> the config references must exist, or
the backend refuses to start. For example, the custom sign-in provider
references auth_provider/custom/client_secret, which can stay "" while that
provider is off. If the backend image did not change in the same update, run
docker compose restart maintmode for the new config to take effect.
Taking a newer compose.yaml? Valkey now requires a password. Generate
one (openssl rand -hex 32), set it as VALKEY_PASSWORD in .env and as
valkey/password in config/app.secrets.yaml, then run both
docker compose up -d and docker compose restart maintmode: up -d
recreates Valkey with the new password but leaves a running backend on the old
one. Until VALKEY_PASSWORD is set, compose refuses to start and names it.
To roll back, set the previous tag and up -d again — but note that a
migration applied by the newer version is not undone, and an older backend
may not tolerate a newer schema. Restoring from backup is the reliable path.
From backend v0.4.0 and frontend v0.4.0, the backend accepts sign-in and
token-refresh calls only from a frontend that presents its credential. The new
backend refuses to start without the s2s section in config/app.config.yaml,
and an older backend refuses to start with it — so the configuration and both
images move in one step:
- Generate the credential (
openssl rand -hex 32). Put it in.envasMAINTMODE_BACKEND_S2S_TOKENand inconfig/app.secrets.yamlass2s/maintmode-ui/secret. - Take
compose.yamland thes2ssection ofconfig/app.config.yamlfrom this repository. - Set
MAINTMODE_VERSIONtov0.4.0andMAINTMODE_UI_VERSIONtov0.4.0(or later; both at once), thendocker compose pull && docker compose up -d.
Compose starts the new backend first and the frontend once the backend is
healthy; for the half-minute in between, sign-ins and session refreshes from
the old frontend are refused. To roll back, set the previous
MAINTMODE_VERSION, remove the s2s section from config/app.config.yaml,
and docker compose up -d. Keep the frontend on the new tag: an older backend
ignores its credential.
v0.1.x let the frontend run Google sign-in; newer versions run it in the
backend, behind the gateway. The configuration changed with it, and a newer
backend refuses to start on an old config/app.config.yaml (unknown keys are
an error, not ignored). Pull this repository's current files, then:
- Take
compose.yaml,gateway/Caddyfile, andconfig/app.config.yamlfrom this repository, and carry over your own values (frontend_urland anything you had changed). Then setoauth_providers.providers.google.client_id(the client ID, which used to live in the secrets file) andoauth_providers.providers.google.redirect_uri(see step 6). - In
config/app.secrets.yaml, removeoauth/google/client_idand addauth_provider/google/client_secret(your Google client secret, which used to live in.env) andbootstrap/password(seeconfig/app.secrets.example.yaml). - Remove
MAINTMODE_GOOGLE_OAUTH_CLIENT_IDandMAINTMODE_GOOGLE_OAUTH_CLIENT_SECRETfrom.env. - In Google Cloud Console, add the new redirect URI
(
<MAINTMODE_APP_BASE_URL>/auth/api/v1/login/oauth/google/callback). Remove the old/api/auth/callback/googleone once sign-in works. docker compose up -d.
Existing users lose their Google link. The upgrade's migrations clear the table that ties an account to its Google identity, so after it every user's Google sign-in is refused as an unknown account. Accounts, roles and data are kept; only the link is gone, and inviting an existing address is refused. To restore access:
- Sign in through break-glass and set up the email integration.
- Turn on sign-in by emailed code under the admin UI's authentication settings.
- Each user signs in with an emailed code, then links Google again from their profile's sign-in methods.
Two things need backing up, and a database dump alone is not enough:
- The database — all your data.
config/app.secrets.yaml— specificallycrypto/kek/selfhost-1. It is the key that decrypts your stored integration credentials. Restore a database without it and MaintMode comes up with your Slack and SMTP integrations listed but their credentials unreadable, and you have to enter them again.
Store them separately: a backup holding both an encrypted dump and the key that decrypts it offers little protection.
A dump also holds personal data: client IP addresses, kept in refresh-token
rows for at most jwt.refresh_token_ttl plus
task_processor.refresh_token_prune.retention (31 days by default) and in the
audit log for task_processor.audit_prune.retention (365 days by default).
Valkey does not need backing up — it holds only rate-limit counters and short-lived locks, all of which regenerate.
docker compose exec -T postgres \
pg_dump -U maintmode -d maintmode -Fc \
> maintmode-$(date +%F).dump-Fc is Postgres's custom format: compressed, and restorable with
pg_restore. Verify the file is non-trivial in size, then copy it off the
host — a backup on the same disk as the database is not a backup.
For a nightly cron job:
0 3 * * * cd /path/to/maintmode-selfhost && docker compose exec -T postgres pg_dump -U maintmode -d maintmode -Fc > /backups/maintmode-$(date +\%F).dump(% must be escaped as \% in a crontab.)
Restoring replaces existing data, so stop the applications first — leaving them running against a database being rewritten produces inconsistent results.
# 1. Stop the apps, keep the database running
docker compose stop ui maintmode
# 2. Drop and recreate the schema
docker compose exec -T postgres \
psql -U maintmode -d maintmode \
-c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
# 3. Restore
docker compose exec -T postgres \
pg_restore -U maintmode -d maintmode --no-owner \
< maintmode-2026-01-15.dump
# 4. Start back up
docker compose up -dMake sure config/app.secrets.yaml holds the same crypto/kek/selfhost-1
value it had when the dump was taken, before starting back up.
To restore onto a brand-new host, copy .env and config/app.secrets.yaml
across first, run docker compose up -d once to create the volumes and apply
migrations, then follow the steps above.
Start here for anything:
docker compose ps # which containers are up, healthy, or exited
docker compose logs ui # frontend
docker compose logs maintmode
docker compose logs migrationsThe most common failure. Google is comparing the redirect URI your instance sent against the ones registered on the client, as exact strings.
The error page shows the URI that was actually sent. Compare it, character by character, against APIs & Services → Credentials → your client → Authorized redirect URIs. Usual culprits:
httpvshttps— behind a proxy,MAINTMODE_APP_BASE_URLmust be thehttpsURL, not the internalhttpone- A trailing slash on
MAINTMODE_APP_BASE_URL localhostvs127.0.0.1— different strings to Google- A missing or extra port
- The path — it is
/auth/api/v1/login/oauth/google/callback, with the/authprefix redirect_uriinconfig/app.config.yamldiffers from the registered one — it is the URI the backend actually sends
After correcting redirect_uri in config/app.config.yaml, run
docker compose restart maintmode; after correcting MAINTMODE_APP_BASE_URL
in .env, docker compose up -d (see
Applying configuration changes). Google's changes can take
a few minutes to propagate. This error never shows up in MaintMode's logs:
Google rejects the request on its side before your instance is involved.
Almost always an invalid auth variable. MAINTMODE_AUTH_SECRET,
MAINTMODE_APP_BASE_URL, and MAINTMODE_AUTH_PUBLIC_BASE_URL (which
compose.yaml derives from MAINTMODE_APP_BASE_URL) are checked in two places:
- Missing or empty:
docker compose uprefuses to start and names the variable, before any container is created. - Present but invalid — a secret shorter than 32 characters, a URL without
its scheme: Compose cannot tell, so the frontend container starts. The
values are validated when the auth module loads, on the first request, so
every page answers HTTP 500,
/loginincluded. Theuihealthcheck requests/loginand fails on that 500: about 40 seconds after startdocker compose psshowsuiasunhealthy, anddocker compose up -dstops withdependency failed to start: container …-ui-1 is unhealthy. On a first start that means the gateway never starts and nothing answers on the published port; a gateway that was already running keeps serving the 500s.
An unhealthy ui means the frontend's own configuration, not a backend
outage: the check does not depend on the backend. If the backend goes down
after start-up, /login still renders its password form and ui stays
healthy (see
The backend never becomes healthy for
that case).
The error appears in the frontend log (the healthcheck's own requests put it there), and names the offending variable:
docker compose logs uiCheck:
- Both are present in
.envwith no empty values MAINTMODE_AUTH_SECRETis at least 32 charactersMAINTMODE_APP_BASE_URLis a full URL including the scheme- No stray quotes around values —
.envis not shell, soKEY="value"makes the quotes part of the value
Fix .env, then docker compose up -d.
Google authenticated you, but the backend did not sign you in. Check the
backend log first — unlike redirect_uri_mismatch, these reach it:
docker compose logs maintmode | grep -i oauth- No invitation. The account has no invitation and
allow_open_signupisfalse, so signup is refused by design — on a fresh instance too. Sign in through break-glass and invite the account; the invitee must sign in through the link in the invitation email. - Wrong client secret. The code exchange with Google fails. Compare
auth_provider/google/client_secretinconfig/app.secrets.yamlwith the secret in Google Cloud Console, andclient_idinconfig/app.config.yamlwith the client ID. - Sign-in ends with a
state_invaliderror. The short-lived sign-in cookie did not come back to the callback:app.oauth_cookie_pathwas changed, or a proxy in front rewrites paths. Restore/auth/api/v1/login/oauthand make sure the proxy passes paths through unchanged. (It also appears when the sign-in took longer than ten minutes; just try again.)
All three fixes are in config/, so apply them with
docker compose restart maintmode.
Sign-ins fail as "invalid credentials", and users who are already signed in get an HTTP 503 once their session needs refreshing. Their sessions are kept and recover on their own once the values match.
The frontend's credential does not match the backend's: compare
MAINTMODE_BACKEND_S2S_TOKEN in .env with s2s/maintmode-ui/secret in
config/app.secrets.yaml — they must be identical, and compose cannot check
that for you. After fixing either, run docker compose up -d (for .env) and
docker compose restart maintmode (for the secrets file).
docker compose logs migrations- Authentication failure: the password in
db/dsndoes not matchPOSTGRES_PASSWORD. Note thatPOSTGRES_PASSWORDonly takes effect on the first start — if you changed it afterwards, Postgres still enforces the original. Either setdb/dsnback to the original, or wipe the volume withdocker compose down -v(destroys all data). - Cannot connect: Postgres has not become healthy.
docker compose ps, and check its logs. - A migration errored: the schema is now partly applied. Restore from backup rather than improvising; the backend deliberately refuses to start.
The backend will not start until this job exits 0, so a stuck migration presents as a backend that never starts.
The images are public, so this is almost always a stale credential rather than a permission you are missing. Docker sends whatever it has stored for the registry, and a token that no longer grants access to the package fails the pull that would have succeeded anonymously:
docker logout ghcr.io
docker compose pullIf it still fails, check the tag exists — MAINTMODE_VERSION must name a
published release tag, a branch, a sha- tag or latest.
Error starting userland proxy: listen tcp4 127.0.0.1:3000: bind: address already in use
Something else holds port 3000. Either stop it, or pick another port in .env:
MAINTMODE_HTTP_PORT=3001
If you are not behind a reverse proxy, the port is part of your public URL,
so also update MAINTMODE_APP_BASE_URL, app.frontend_url and
oauth_providers.providers.google.redirect_uri in config/app.config.yaml,
and the redirect URI in Google Cloud Console, then run docker compose up -d
and docker compose restart maintmode. Behind a proxy, only the proxy's
upstream needs changing.
docker compose logs maintmodeStartup validates configuration strictly and fails loudly rather than running degraded:
jwt.issuer_private_key is unusable— not 64 hex characters, or generated withecparaminstead ofrand -hex 32jwt.issuer_private_key is a placeholder— all one repeated byte- A missing secrets key — every
<secret:...>reference inapp.config.yamlmust exist inapp.secrets.yaml - A permission error reading
/app/app.secrets.yaml— the container's unprivileged user cannot read it;chmod 644 config/app.secrets.yaml has invalid keyswhile reading the config — a key the backend no longer reads, usually a config from an older version. See Upgrading from v0.1.x
docker compose down -vDeletes the containers and the volumes, so all data is gone. .env and
config/app.secrets.yaml survive, since they are files in your working tree.
The next up -d starts a fresh instance with no users: sign in through
break-glass again.
Self-hosted MaintMode is free, unlimited, and does not phone home. No seat counting, no licence check, no usage reporting, no update pings.
This is not a policy promise — it is how the code is structured, and you can verify it. The backend contains licence-enforcement code because the same binary also runs the paid hosted service. That code activates only when both a console URL and an instance token are configured:
func (c LicenseConfig) Enabled() bool {
return c.URL != "" && c.InstanceToken != ""
}A half-configured block stays off. config/app.config.yaml in this repository
has no license: section at all, so both are empty and the gate reports
disabled. In that state the heartbeat job is never registered, the licence HTTP
client is never constructed, no seat cap is applied, and no request leaves your
instance. There is no code path that reaches the licence server without those
two values.
The only outbound connections a running instance makes are:
- Google (
accounts.google.com,oauth2.googleapis.com,www.googleapis.com), during sign-in: the code exchange and the public keys that verify its result. It carries nothing beyond the sign-in itself. - Whatever you configure yourself — Slack, Telegram, or your SMTP server, once you set up notifications.
Nothing else.
All three repositories — backend, frontend, and this one — are licensed under the GNU Affero General Public License v3.0. The full text is in LICENSE.
What that means in practice:
- Running it internally, modified or not, obliges you to nothing. Use it for your team, change it, keep the changes private.
- The network clause (section 13) applies if you offer a modified version to users over a network. Run your own modified MaintMode as a service that other people use, and those users are entitled to the source of your modified version. Running an unmodified version, or running a modified one only for your own organisation's internal use, does not trigger this.
- Redistributing it, modified or not, requires the same licence and that you pass on the source.
This is a summary, not legal advice. Read LICENSE if the distinction matters to you.
| File | Purpose |
|---|---|
compose.yaml |
The stack: Postgres, Valkey, migrations, backend, frontend, gateway |
gateway/Caddyfile |
The gateway: routes the two sign-in routes to the backend, everything else to the frontend |
.env.example |
Template for .env — database, session, and public URL |
config/app.config.yaml |
Backend configuration, mounted read-only. Committed; holds no secrets |
config/app.secrets.example.yaml |
Template for config/app.secrets.yaml — signing key, encryption key, database DSN, Google client secret, break-glass password |
.gitignore |
Keeps .env, secrets, and dumps out of git |
LICENSE |
AGPL-3.0 |
- Bugs and questions about the backend or the API — maintmode-dev/maintmode
- Bugs in the web interface — maintmode-dev/maintmode-ui
- Problems with this Compose setup or these instructions — open an issue here
When reporting a bring-up problem, include the output of docker compose ps and
the relevant docker compose logs, with secrets redacted.