Documentation menu▾

Installation

Deploy Keygate with Docker Compose or from source: HTTPS behind a proxy, backups, upgrades with version notes, rolling back, multiple instances and a go-live checklist.

Keygate is a Go server that keeps everything in PostgreSQL. A small virtual server is enough for most products: it serves the API, the admin dashboard and the customer portal from the same process. This page covers putting it on a server you control and keeping it healthy. If you only want to try it, the quick start is faster.

Requirements

  • A Linux server or VM with a public domain name pointing at it.
  • Docker with Compose 2.24 or later, or Go 1.27 and Bun if you build from source.
  • PostgreSQL. The compose file runs PostgreSQL 18 for you; you can also use a managed database.
  • Optional: S3 compatible storage (AWS S3, Cloudflare R2, MinIO) if you want Keygate to host your app's releases, and Redis or Valkey if you run more than one instance.

Docker Compose

This is the recommended way to run Keygate. Download the two files into a folder:

bash
mkdir keygate && cd keygate
curl -O https://raw.githubusercontent.com/tabloy/keygate/main/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/tabloy/keygate/main/.env.example

Edit .env. At a minimum set JWT_SECRET and LICENSE_SIGNING_KEY to random values (openssl rand -hex 32 makes one) and BASE_URL to the address people will use, such as https://licenses.example.com. Then start it:

bash
docker compose up -d

Everything in .env reaches the container. A few values are set in the compose file itself and win over .env: the port, ENVIRONMENT=production and the database address, which points at the bundled PostgreSQL. To use your own database, change DATABASE_URL in docker-compose.yml and remove the postgres service.

The configuration reference lists every setting.

Build from source

If you would rather not use Docker, build Keygate from source. You need Go 1.27 and Bun:

bash
git clone https://github.com/tabloy/keygate.git
cd keygate
cp .env.example .env
make build
./bin/keygate

make build builds the server into bin/keygate and the dashboard into web/dist. Start it from the repository folder: it reads .env, the database migrations in db/migrations and the dashboard in web/dist from the folder it starts in, and real environment variables take precedence over the file. Run it under systemd or another supervisor, with that folder as the working directory, so it restarts after a crash or a reboot.

HTTPS and your domain

Keygate listens on plain HTTP, port 9000 by default. Put a reverse proxy in front of it to handle HTTPS. With Caddy this is the entire configuration, certificates included:

Caddyfile
licenses.example.com {
	reverse_proxy localhost:9000
}

Whatever you use, set BASE_URL to the public HTTPS address. Keygate builds links with it: the links in emails, the return address after Stripe Checkout, the webhook address it registers with Stripe and the update feed addresses shown in Update settings, which warns you when BASE_URL still points at localhost. A subdomain of your product's domain, such as licenses.yourapp.com, works well, because your customers see it in the portal and in emails.

The client's address

Rate limits and the brute force lockout count per client address. That is the address of the connection, unless the connection comes from a proxy listed in TRUSTED_PROXIES: Keygate then takes the address the proxy reports in X-Forwarded-For, or X-Real-Ip. Left unset, the trusted proxies are the private networks (10.x, 172.16 to 172.31, 192.168.x, fc00::/7).

Trust only an HTTP proxy that sets or appends X-Forwarded-For and overwrites X-Real-Ip. Caddy does both as it is. With nginx, add them yourself:

nginx
location / {
    proxy_pass http://localhost:9000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Then name the address your proxy connects from:

SetupTRUSTED_PROXIES
nginx or Caddy on the same machine, Keygate run from source127.0.0.1,::1
A proxy on the host in front of the Docker containerThe Docker network's gateway, such as 172.18.0.1
A proxy in another container on the same Docker networkThat network, such as 172.18.0.0/16
No proxy, port 9000 published directlynone

Not sure which address it is? Before you set TRUSTED_PROXIES, Keygate's request log shows the proxy's address as the client of every request.

Never list a plain TCP forwarder, such as socat, an SSH tunnel or a load balancer in TCP mode: it passes a client's own headers through, so the client would choose the address its limits count under. Behind Cloudflare, every request comes from Cloudflare's addresses and customers share one address. Its ranges are not trusted by default, because a Cloudflare Worker or WARP client can write these headers too.

Admin accounts

The owner account is created on the setup page the first time you open Keygate, see the quick start. If ADMIN_EMAILS is set by then, the setup page only accepts one of those emails. Invite other admins from Team in the dashboard settings, or list their emails in ADMIN_EMAILS so they become admins the first time they sign in. Everyone signs in with a one time code sent by email, so set up email delivery before you invite anyone.

Backups

All state lives in PostgreSQL, apart from release files in object storage. Back up the database on a schedule. With the bundled database:

bash
docker compose exec postgres pg_dump -U keygate keygate > keygate-backup.sql

Keep these secrets with your backups, somewhere safe and separate from the server:

  • LICENSE_SIGNING_KEY signs the offline tokens your app checks. If it changes, apps that store the old public key reject every new token.
  • RELEASE_KEY_ENCRYPTION_KEY encrypts release signing keys, email provider credentials and stored license keys. Without it they cannot be decrypted.
  • JWT_SECRET signs login sessions. Changing it only signs everyone out.

Upgrading

Read the release notes, take a backup, then pull the new image and restart:

bash
docker compose pull
docker compose up -d

Database migrations run on their own when the new version starts. The compose file follows latest, which is the easiest way to stay current. If you would rather upgrade only when you decide, replace latest with a version number from the release notes:

docker-compose.yml
image: ghcr.io/tabloy/keygate:x.y.z

Migrations usually take a few seconds. One that rebuilds a large table can take longer, and Keygate starts serving once it is done. A single migration statement may run for up to five minutes; if one runs out of time, that migration is rolled back and Keygate stops with the error in its log.

Version notes

Most releases need nothing beyond pulling the new image. The ones that do say so under Upgrade notes in their release notes. If you skip versions, read the notes of every release in between. These are the releases with steps of their own.

v0.1.19 adds two migrations. Rolling back to v0.1.18 only takes the older image, which runs on the new schema:

  • 20261030_audit_product adds a product column and an index to audit_logs, and locks that table while it runs: about 0.4 to 1.3 seconds per million rows. Other tables are not affected. With a large audit table, create both first, without blocking: ALTER TABLE audit_logs ADD COLUMN IF NOT EXISTS product_id TEXT; then CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_audit_product ON audit_logs(product_id, created_at);
  • A full refund of the current period now cancels the Stripe subscription, and a lost dispute cancels it and revokes the license. A refund of a past period, or one matched to a license only through the customer, no longer revokes it. See cancellations and refunds.
  • Give a restricted Stripe key read access to Charges: lost disputes read the charge.
  • A trial that Stripe does not bill, on a plan with no fallback plan, gets no grace days in verify answers or the token's grc: the hourly check already ended it at its end date.
  • Per-seat licenses created through the admin API before v0.1.19 have quantity 1. Raise it with POST /admin/licenses/:id/quantity where the plan sells more.

v0.1.18 has no migrations, so rolling back to v0.1.17 only takes the older image:

  • Flag features (value_type flag, set through the admin API) are now JSON booleans in verify answers and in the token's ftr, as bool features already were. Tokens issued by v0.1.17 keep the strings until they expire, so an app should accept both for that time.
  • A flag is off only when its value is false. Older values such as 1 or yes count as on. To find them: SELECT feature, value FROM entitlements WHERE value_type = 'flag' AND value NOT IN ('true', 'false');
  • A Stripe webhook whose license update fails now answers 500, so Stripe sends it again. v0.1.17 still answers 200, so keep the time both versions run side by side short.

v0.1.17 adds member license keys, plans sold per seat and trial fallback plans:

  • Stop every instance of an older version before you start v0.1.17, including when you run more than one instance. An older instance does not know about member keys or trial fallbacks, so the two cannot run side by side.
  • A plan's max seats now counts the owner: it is the number of people a license holds. The upgrade raises every plan at 2 or more by one, so those licenses keep the room they had. A plan at 1 now holds the owner alone, and members already on such licenses are paused until you raise the plan's max seats. If you set max seats from a script or the admin API, count the owner from now on. 0 still means no limit.
  • Each member gets a license key of their own the first time they open the customer portal, or when an admin reveals it in the dashboard. Members can keep using the license key until then. A device a member activated with that shared key moves to the member when they activate it with their own key.
  • The member admin role is gone. Only the license owner manages members, and members who were admins become ordinary members.
  • Set a trial fallback plan only once every instance runs v0.1.17. If you customized the Trial Expired or License Expiring email template, add {{.FallbackPlan}} so customers are told which plan their trial moves to.

Rolling back

The previous version normally starts fine on a database the new one has migrated. If a release note says otherwise, follow its steps, or restore the backup you took before upgrading.

Going back from v0.1.17 to v0.1.16 is one of those cases. Keygate only runs migrations forward, so before you start v0.1.16, run the down migrations of v0.1.17 yourself, newest first, from 20261029 back to 20261025, and delete each one's record from schema_migrations once it has run: Keygate skips any migration recorded there, so a later upgrade would not apply them again. The script stops at the first error, so a record is never deleted for a migration that did not run. With the bundled database:

bash
set -euo pipefail
docker compose stop keygate
for m in 20261029_plan_trial_fallback 20261028_member_keys 20261027_per_seat_quantity \
         20261026_license_key_prefix 20261025_seats_include_owner; do
  curl -fsSL "https://raw.githubusercontent.com/tabloy/keygate/v0.1.17/db/migrations/$m.down.sql" |
    docker compose exec -T postgres psql -U keygate -d keygate -v ON_ERROR_STOP=1
  docker compose exec -T postgres psql -U keygate -d keygate -v ON_ERROR_STOP=1 -c \
    "DELETE FROM schema_migrations WHERE filename = '$m.up.sql'"
done

If you built from source, run the same files from db/migrations of v0.1.17 with psql against your database. Then set the image to ghcr.io/tabloy/keygate:0.1.16 and start it. What v0.1.17 added is lost:

  • Members' own keys stop working and members go back to using the license key. The devices they activated stay on the license, but the app on each one needs the license key entered again.
  • Licenses on plans sold per seat lose the seats bought. Such a plan stores Max Seats 1 and its devices per seat as Max Activations, so v0.1.16 gives each of those licenses one member besides the owner and one seat's devices, while Stripe keeps billing the seats bought.
  • Trial fallbacks are cleared, so trials expire again when they end.
  • Product key prefixes are dropped and new keys start with KG again. Keys already issued with another prefix keep working.
  • Plans with a max seats of 3 or more go down by one, back to v0.1.16's count, which leaves the owner out. Members who were admins stay members.

Running more than one instance

Several Keygate instances can share one database behind a load balancer. Set REDIS_URL on all of them so rate limits are counted together; without it each instance keeps its own count, and three instances allow three times the configured limit. Background work such as reminder emails is claimed through the database, so two instances do not send the same email twice.

When several instances start at once, after an upgrade say, one of them applies the migrations and the others wait for it before they start, for up to ten minutes. The migrations hold a lock on their database connection, so if a connection pooler such as PgBouncer sits in front of PostgreSQL, use session pooling for Keygate or let it connect to PostgreSQL directly: transaction pooling does not keep that lock.

Some releases cannot run beside instances of an older version. Their upgrade notes say so: stop every old instance before the first new one starts. Version notes lists those releases.

Before you go live

  • BASE_URL is your public HTTPS address and the site loads there.
  • The secrets are random, stored safely and included in your backups.
  • Email works: send yourself a test from the email settings.
  • A database backup runs on a schedule, and you have restored one at least once.
  • If you sell through Stripe, a test purchase creates a license. See Selling with Stripe.

Last updated October 27, 2026