Self Hosting

Keygen is designed to be self-hosted through Docker. You don't have to be a Docker expert to launch your own instance of Keygen, but you should have a basic understanding of the command line and networking to successfully set up your own instance of Keygen.

The source code for Keygen can be found on our GitHub.

Editions

There are two editions of Keygen. One tailored to hobbyists and DIYers, and one for businesses.

Community Edition

Keygen CE is the Community Edition of Keygen. Keygen CE is free (as in beer). This is the default edition, but can be explicitly configured with the following environment variable:

KEYGEN_EDITION="CE"
KEYGEN_EDITION="CE"
content_copy

We offer best-effort support for Keygen CE users. If your business runs Keygen and needs dedicated support, consider purchasing Keygen EE or becoming a Keygen Cloud customer.

There is a community-supported Discord server and forum where you can ask for help.

Enterprise Edition

Keygen EE is the Enterprise Edition of Keygen. Keygen EE requires a valid license key to run. To purchase a license key, click here, or reach out for a 30-day no-strings-attached trial.

Keygen EE can be configured with the following environment variables:

KEYGEN_LICENSE_FILE_PATH="/etc/keygen/ee.lic"
KEYGEN_LICENSE_KEY="C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3"
KEYGEN_EDITION="EE"
KEYGEN_LICENSE_FILE_PATH="/etc/keygen/ee.lic"
KEYGEN_LICENSE_KEY="C1B6DE-39A6E3-DE1529-8559A0-4AF593-V3"
KEYGEN_EDITION="EE"
content_copy

Keygen EE enables the following features:

• Request logs: keep a historical record of API requests, along with who made the request, the request body, response body, status code, IP address, and other information.
• Event logs: keep an audit trail of every single event that happens on a Keygen account.
• Environments: manage separate environments within a Keygen account, from test environments, to a sandbox, to QA, to production.
• Permissions: enterprise-grade roles and permissions.
• SSO/SAML: support for SSO/SAML coming soon.

In addition, Keygen EE customers are entitled to dedicated support.

To purchase a Keygen EE license, click here. Not ready to purchase? Contact sales with any questions, or for a 30-day no-strings-attached trial of Keygen EE.

We'd love to get your team set up!

Modes

There are also two modes of Keygen.

Singleplayer mode

The single-tenant mode of Keygen. This is the default mode, but can be explicitly configured with the following environment variable:

KEYGEN_MODE="singleplayer"
KEYGEN_MODE="singleplayer"
content_copy

Multiplayer mode

The multi-tenant mode of Keygen. This mode requires a Keygen EE license with the multiplayer entitlement. Currently, Keygen Cloud is the only multiplayer instance of Keygen.

KEYGEN_MODE="multiplayer"
KEYGEN_MODE="multiplayer"
content_copy

If you're interested in multiplayer mode, please reach out.

Versioning

Keygen follows semantic versioning. You can find all available Keygen versions on Docker Hub.

The default latest tag refers to the latest stable release tag.

You can also pin your version:

• keygen/api:v1 pins the major version to 1 but allows minor and patch version upgrades.
• keygen/api:v1.3 pins the minor version to 1.3 but allows only patch upgrades.

The self-hosted versions of Keygen are somewhat of a Long-Term Support (LTS) release, getting a new release twice a year after being battle tested in Keygen Cloud. If you want features as soon as they're available, consider becoming a Keygen Cloud customer, or alteratively, build the Docker image from source (but understand the risks associated with running edge software).

After reviewing what other maintainers of popular open-source projects do, it seems like a bi-yearly schedule works well for everyone vs. more frequent updates:

• Self-hosters can upgrade their setup less frequently, which saves them time spent on maintenance and reduces their workload.
• We can cut new self-hosted releases less frequently and are able to put more effort into creating a better release DX.

No functionality or bug fixes will be backported to older versions. If you wish to get the latest bug fixes and security updates, you can upgrade to the latest version.

The Docker image and Keygen's API itself are versioned separately. For information on our API's versioning policy, please see Versioning.

You can subscribe to version updates via our RSS feed:

https://github.com/keygen-sh/keygen-api/tags.atom
https://github.com/keygen-sh/keygen-api/tags.atom
content_copy

Use your favorite RSS reader.

Requirements

The only thing you need to install Keygen is a server with Docker installed. The server must have a CPU with the x86_64 architecture, and support for SSE 4.2 instructions. We recommend using a minimum of 500MB of RAM, but exact requirements will depend on configuration.

If your server does not have Docker installed, you can follow their instructions.

Keygen requires Ruby >= 3.1, Postgres >= 13, and Redis >= 6.2.

Installation

Installing Keygen can be done in a few ways, depending on if you're just checking out Keygen CE or if you're looking to self-host Keygen EE for production use.

Docker Hub

The easiest way to get started with Keygen is to pull via Docker Hub.

docker pull keygen/api
docker pull keygen/api
content_copy

For most production deployments, you will use Docker Hub.

Clone the repository

Alternatively, you can clone the GitHub repository and build the image manually:

git clone https://github.com/keygen-sh/keygen-api
git clone https://github.com/keygen-sh/keygen-api
content_copy

After cloning, you can can build the Docker image:

docker build -t keygen/api .
docker build -t keygen/api .
content_copy

Tarball

Alternatively, you can download and extract a tarball from GitHub:

curl -L https://github.com/keygen-sh/keygen-api/archive/master.tar.gz | tar -xz
curl -L https://github.com/keygen-sh/keygen-api/archive/master.tar.gz | tar -xz
content_copy

After downloading, you can build the Docker image.

Configuration

Keygen is a twelve-factor app, therefore configuring Keygen can be accomplished using environment variables. Keygen can be configured with the following variables:

Configure Postgres

Keygen's main application database is Postgres. The minimum supported version is Postgres 13. Storage and connection requirements will vary depending on volume.

You can set the Postgres database using the following environment variable:

DATABASE_URL="postgres://postgres:postgres@localhost:5432"
DATABASE_URL="postgres://postgres:postgres@localhost:5432"
content_copy

To start a non-production Postgres container, run:

docker run --name postgres -d -p 5432:5432 \
  -v postgres:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=postgres \
  postgres
docker run --name postgres -d -p 5432:5432 \
  -v postgres:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=postgres \
  postgres
content_copy

Ensure Postgres is running before proceeding.

Configure Redis

Keygen's cache and background job database is Redis. The minimum supported version is Redis 6.2. Storage and connection requirements will vary.

You can set the Redis database using the following environment variable:

REDIS_URL="redis://localhost:6379"
REDIS_URL="redis://localhost:6379"
content_copy

To start a non-production Redis container, run:

docker run --name redis -d -p 6379:6379 \
  -v redis:/var/lib/redis/data \
  redis
docker run --name redis -d -p 6379:6379 \
  -v redis:/var/lib/redis/data \
  redis
content_copy

Ensure Redis is running before proceeding.

Configure Keygen

The easiest way to get Keygen set up is to use the setup command. It will walk you through the necessary steps to set up your Keygen instance and environment.

docker run --rm -it -e SECRET_KEY_BASE="$(openssl rand -hex 64)" \
  -e ENCRYPTION_DETERMINISTIC_KEY="$(openssl rand -base64 32)" \
  -e ENCRYPTION_PRIMARY_KEY="$(openssl rand -base64 32)" \
  -e ENCRYPTION_KEY_DERIVATION_SALT="$(openssl rand -base64 32)" \
  -e DATABASE_URL="postgres://postgres:[email protected]:5432/postgres" \
  -e REDIS_URL="redis://host.docker.internal:6379" \
  -e KEYGEN_HOST="api.keygen.localhost" \
  -e KEYGEN_MODE="singleplayer" \
  -e KEYGEN_EDITION="EE" \
  keygen/api setup
docker run --rm -it -e SECRET_KEY_BASE="$(openssl rand -hex 64)" \
  -e ENCRYPTION_DETERMINISTIC_KEY="$(openssl rand -base64 32)" \
  -e ENCRYPTION_PRIMARY_KEY="$(openssl rand -base64 32)" \
  -e ENCRYPTION_KEY_DERIVATION_SALT="$(openssl rand -base64 32)" \
  -e DATABASE_URL="postgres://postgres:postgres@host.docker.internal:5432/postgres" \
  -e REDIS_URL="redis://host.docker.internal:6379" \
  -e KEYGEN_HOST="api.keygen.localhost" \
  -e KEYGEN_MODE="singleplayer" \
  -e KEYGEN_EDITION="EE" \
  keygen/api setup
content_copy

Please note that Postgres and Redis must be setup and running beforehand.

After running the setup command, set the resulting environment variables.

Running

Keygen has two processes types, server and worker.

Starting the server

Keygen uses Puma as its web server to serve the API. By default, the server listens for HTTP(S) requests on port 3000. The server only supports HTTP 1.1, it does NOT support HTTP 2.

To start the server, run the following command:

docker run --name web.1 -p 127.0.0.1:3000:3000 -e SECRET_KEY_BASE="${SECRET_KEY_BASE}" \
  -e ENCRYPTION_DETERMINISTIC_KEY="${ENCRYPTION_DETERMINISTIC_KEY}" \
  -e ENCRYPTION_PRIMARY_KEY="${ENCRYPTION_PRIMARY_KEY}" \
  -e ENCRYPTION_KEY_DERIVATION_SALT="${ENCRYPTION_KEY_DERIVATION_SALT}" \
  -e DATABASE_URL="postgres://postgres:[email protected]:5432/postgres" \
  -e REDIS_URL="redis://host.docker.internal:6379" \
  -e KEYGEN_LICENSE_FILE_PATH="${KEYGEN_LICENSE_FILE_PATH}" \
  -e KEYGEN_LICENSE_KEY="${KEYGEN_LICENSE_KEY}" \
  -e KEYGEN_ACCOUNT_ID="${KEYGEN_ACCOUNT_ID}" \
  -e KEYGEN_EDITION="${KEYGEN_EDITION}" \
  -e KEYGEN_MODE="${KEYGEN_MODE}" \
  -e KEYGEN_HOST="${KEYGEN_HOST}" \
  -v /etc/keygen:/etc/keygen \
  keygen/api web
docker run --name web.1 -p 127.0.0.1:3000:3000 -e SECRET_KEY_BASE="${SECRET_KEY_BASE}" \
  -e ENCRYPTION_DETERMINISTIC_KEY="${ENCRYPTION_DETERMINISTIC_KEY}" \
  -e ENCRYPTION_PRIMARY_KEY="${ENCRYPTION_PRIMARY_KEY}" \
  -e ENCRYPTION_KEY_DERIVATION_SALT="${ENCRYPTION_KEY_DERIVATION_SALT}" \
  -e DATABASE_URL="postgres://postgres:postgres@host.docker.internal:5432/postgres" \
  -e REDIS_URL="redis://host.docker.internal:6379" \
  -e KEYGEN_LICENSE_FILE_PATH="${KEYGEN_LICENSE_FILE_PATH}" \
  -e KEYGEN_LICENSE_KEY="${KEYGEN_LICENSE_KEY}" \
  -e KEYGEN_ACCOUNT_ID="${KEYGEN_ACCOUNT_ID}" \
  -e KEYGEN_EDITION="${KEYGEN_EDITION}" \
  -e KEYGEN_MODE="${KEYGEN_MODE}" \
  -e KEYGEN_HOST="${KEYGEN_HOST}" \
  -v /etc/keygen:/etc/keygen \
  keygen/api web
content_copy

To access Keygen on localhost over TLS, you can use a reverse proxy such as Caddy:

echo '127.0.0.1 api.keygen.localhost' | sudo tee -a /etc/hosts
caddy reverse-proxy --from api.keygen.localhost --to :3000
echo '127.0.0.1 api.keygen.localhost' | sudo tee -a /etc/hosts
caddy reverse-proxy --from api.keygen.localhost --to :3000
content_copy

Feel free to use a different reverse proxy, such as Traefik, Nginx, or Apache.

Keygen should now be available at:

curl -I https://api.keygen.localhost/v1/ping
# HTTP/2 200
# ...
curl -I https://api.keygen.localhost/v1/ping
# HTTP/2 200
# ...
content_copy

If you're unable to ping the server, check the logs. Keygen logs to stdout by default. If you're able to ping the server but it redirects, your reverse proxy may not be providing forwarding information (see above i.r.t. well-behaved reverse proxies).

For health checks, use the /v1/health endpoint.

Starting a worker

Keygen uses Sidekiq to process background jobs, including jobs for license expirations, webhooks, machine heartbeats, and more.

To start Sidekiq, run the following command:

docker run --name worker.1 -e SECRET_KEY_BASE="${SECRET_KEY_BASE}" \
  -e ENCRYPTION_DETERMINISTIC_KEY="${ENCRYPTION_DETERMINISTIC_KEY}" \
  -e ENCRYPTION_PRIMARY_KEY="${ENCRYPTION_PRIMARY_KEY}" \
  -e ENCRYPTION_KEY_DERIVATION_SALT="${ENCRYPTION_KEY_DERIVATION_SALT}" \
  -e DATABASE_URL="postgres://postgres:[email protected]:5432/postgres" \
  -e REDIS_URL="redis://host.docker.internal:6379" \
  -e KEYGEN_LICENSE_FILE_PATH="${KEYGEN_LICENSE_FILE_PATH}" \
  -e KEYGEN_LICENSE_KEY="${KEYGEN_LICENSE_KEY}" \
  -e KEYGEN_ACCOUNT_ID="${KEYGEN_ACCOUNT_ID}" \
  -e KEYGEN_EDITION="${KEYGEN_EDITION}" \
  -e KEYGEN_MODE="${KEYGEN_MODE}" \
  -e KEYGEN_HOST="${KEYGEN_HOST}" \
  -v /etc/keygen:/etc/keygen \
  keygen/api worker
docker run --name worker.1 -e SECRET_KEY_BASE="${SECRET_KEY_BASE}" \
  -e ENCRYPTION_DETERMINISTIC_KEY="${ENCRYPTION_DETERMINISTIC_KEY}" \
  -e ENCRYPTION_PRIMARY_KEY="${ENCRYPTION_PRIMARY_KEY}" \
  -e ENCRYPTION_KEY_DERIVATION_SALT="${ENCRYPTION_KEY_DERIVATION_SALT}" \
  -e DATABASE_URL="postgres://postgres:postgres@host.docker.internal:5432/postgres" \
  -e REDIS_URL="redis://host.docker.internal:6379" \
  -e KEYGEN_LICENSE_FILE_PATH="${KEYGEN_LICENSE_FILE_PATH}" \
  -e KEYGEN_LICENSE_KEY="${KEYGEN_LICENSE_KEY}" \
  -e KEYGEN_ACCOUNT_ID="${KEYGEN_ACCOUNT_ID}" \
  -e KEYGEN_EDITION="${KEYGEN_EDITION}" \
  -e KEYGEN_MODE="${KEYGEN_MODE}" \
  -e KEYGEN_HOST="${KEYGEN_HOST}" \
  -v /etc/keygen:/etc/keygen \
  keygen/api worker
content_copy

Sidekiq should now be running.

Managing

Keygen can be managed directly via the API (see API reference), or via the console.

Opening a console

Keygen is a Ruby on Rails app, and as such, supports the rails console command. This allows you to programatically manage your data. You can, for example, set up a product and generate an API token, or create a license for a new customer.

To open a console, run the following command:

docker run --rm -it -e SECRET_KEY_BASE="${SECRET_KEY_BASE}" \
  -e ENCRYPTION_DETERMINISTIC_KEY="${ENCRYPTION_DETERMINISTIC_KEY}" \
  -e ENCRYPTION_PRIMARY_KEY="${ENCRYPTION_PRIMARY_KEY}" \
  -e ENCRYPTION_KEY_DERIVATION_SALT="${ENCRYPTION_KEY_DERIVATION_SALT}" \
  -e DATABASE_URL="postgres://postgres:[email protected]:5432/postgres" \
  -e REDIS_URL="redis://host.docker.internal:6379" \
  -e KEYGEN_LICENSE_FILE_PATH="${KEYGEN_LICENSE_FILE_PATH}" \
  -e KEYGEN_LICENSE_KEY="${KEYGEN_LICENSE_KEY}" \
  -e KEYGEN_ACCOUNT_ID="${KEYGEN_ACCOUNT_ID}" \
  -e KEYGEN_EDITION="${KEYGEN_EDITION}" \
  -e KEYGEN_MODE="${KEYGEN_MODE}" \
  -e KEYGEN_HOST="${KEYGEN_HOST}" \
  -v /etc/keygen:/etc/keygen \
  keygen/api console
docker run --rm -it -e SECRET_KEY_BASE="${SECRET_KEY_BASE}" \
  -e ENCRYPTION_DETERMINISTIC_KEY="${ENCRYPTION_DETERMINISTIC_KEY}" \
  -e ENCRYPTION_PRIMARY_KEY="${ENCRYPTION_PRIMARY_KEY}" \
  -e ENCRYPTION_KEY_DERIVATION_SALT="${ENCRYPTION_KEY_DERIVATION_SALT}" \
  -e DATABASE_URL="postgres://postgres:postgres@host.docker.internal:5432/postgres" \
  -e REDIS_URL="redis://host.docker.internal:6379" \
  -e KEYGEN_LICENSE_FILE_PATH="${KEYGEN_LICENSE_FILE_PATH}" \
  -e KEYGEN_LICENSE_KEY="${KEYGEN_LICENSE_KEY}" \
  -e KEYGEN_ACCOUNT_ID="${KEYGEN_ACCOUNT_ID}" \
  -e KEYGEN_EDITION="${KEYGEN_EDITION}" \
  -e KEYGEN_MODE="${KEYGEN_MODE}" \
  -e KEYGEN_HOST="${KEYGEN_HOST}" \
  -v /etc/keygen:/etc/keygen \
  keygen/api console
content_copy

The console prompt should now be available.

An example of a good first command would be to read your account's public key:

Account.sole.ed25519_public_key
# => "db03db1e0a5e6457da3307a6508f00642fc2549adef32106c609ffff37346813"
Account.sole.ed25519_public_key
# => "db03db1e0a5e6457da3307a6508f00642fc2549adef32106c609ffff37346813"
content_copy

Upgrading

Keygen is updated regularly, but it's up to you to apply these updates on your server.

Using Docker, upgrades are safe and easy to apply.

docker pull keygen/api:latest
docker pull keygen/api:latest
content_copy

New versions of Keygen CE and Keygen EE are released roughly every 6 months.

Migrations

Some upgrades to Keygen may require database schema changes. Database migrations can be run inside of the container using the following rails command:

rails db:migrate
rails db:migrate
content_copy

As part of your deployment process, we typically recommend running a single release container before rolling out an upgrade, which will run the above command.

To run the release command, run the following:

docker run --rm -e SECRET_KEY_BASE="${SECRET_KEY_BASE}" \
  -e ENCRYPTION_DETERMINISTIC_KEY="${ENCRYPTION_DETERMINISTIC_KEY}" \
  -e ENCRYPTION_PRIMARY_KEY="${ENCRYPTION_PRIMARY_KEY}" \
  -e ENCRYPTION_KEY_DERIVATION_SALT="${ENCRYPTION_KEY_DERIVATION_SALT}" \
  -e DATABASE_URL="postgres://postgres:[email protected]:5432/postgres" \
  -e REDIS_URL="redis://host.docker.internal:6379" \
  -e KEYGEN_LICENSE_FILE_PATH="${KEYGEN_LICENSE_FILE_PATH}" \
  -e KEYGEN_LICENSE_KEY="${KEYGEN_LICENSE_KEY}" \
  -e KEYGEN_ACCOUNT_ID="${KEYGEN_ACCOUNT_ID}" \
  -e KEYGEN_EDITION="${KEYGEN_EDITION}" \
  -e KEYGEN_MODE="${KEYGEN_MODE}" \
  -e KEYGEN_HOST="${KEYGEN_HOST}" \
  -v /etc/keygen:/etc/keygen \
  keygen/api release
docker run --rm -e SECRET_KEY_BASE="${SECRET_KEY_BASE}" \
  -e ENCRYPTION_DETERMINISTIC_KEY="${ENCRYPTION_DETERMINISTIC_KEY}" \
  -e ENCRYPTION_PRIMARY_KEY="${ENCRYPTION_PRIMARY_KEY}" \
  -e ENCRYPTION_KEY_DERIVATION_SALT="${ENCRYPTION_KEY_DERIVATION_SALT}" \
  -e DATABASE_URL="postgres://postgres:postgres@host.docker.internal:5432/postgres" \
  -e REDIS_URL="redis://host.docker.internal:6379" \
  -e KEYGEN_LICENSE_FILE_PATH="${KEYGEN_LICENSE_FILE_PATH}" \
  -e KEYGEN_LICENSE_KEY="${KEYGEN_LICENSE_KEY}" \
  -e KEYGEN_ACCOUNT_ID="${KEYGEN_ACCOUNT_ID}" \
  -e KEYGEN_EDITION="${KEYGEN_EDITION}" \
  -e KEYGEN_MODE="${KEYGEN_MODE}" \
  -e KEYGEN_HOST="${KEYGEN_HOST}" \
  -v /etc/keygen:/etc/keygen \
  keygen/api release
content_copy

Some upgrades may require other migrations to be run. For example, some upgrades may require a data migration (e.g. seeding new permissions or event types). These migrations will be detailed in the documentation for the new version.

Monitoring

Server

For server health checks, you can use the following endpoint:

GET https://api.keygen.localhost/v1/health
GET https://api.keygen.localhost/v1/health
content_copy

Using Docker, you can use the --health-cmd flag to monitor the container:

 docker run --name web.1 -p 127.0.0.1:3000:3000 \
+  --health-cmd "wget --no-verbose --tries=1 --spider http://localhost:3000/v1/health || exit 1" \ 
+  --health-interval 5m \ 
+  --health-timeout 60s \ 
   keygen/api console
docker run --name web.1 -p 127.0.0.1:3000:3000 \
  --health-cmd "wget --no-verbose --tries=1 --spider http://localhost:3000/v1/health || exit 1" \ # [tl! ++]
  --health-interval 5m \ # [tl! ++]
  --health-timeout 60s \ # [tl! ++]
  keygen/api console
content_copy

This health endpoint supports both HTTP and HTTPS.

Worker

To access the Sidekiq monitoring UI, set the SIDEKIQ_WEB_USER and SIDEKIQ_WEB_PASSWORD environment variables and visit the following endpoint:

https://api.keygen.localhost/-/sidekiq/
https://api.keygen.localhost/-/sidekiq/
content_copy

You can use this UI to monitor usage and diagnose issues.

Telemetry

Keygen takes your privacy very seriously, and we do not use any form of telemetry.

How does Keygen license Keygen EE without telemetry?

Keygen uses cryptographically signed and encrypted License Files to securely handle licensing Keygen EE without an internet connection.

tl;dr Keygen uses Keygen to license Keygen EE. It's turtles Keygens all the way down.

Tuning

How can I tune Keygen?

Keygen is a standard Rails application, using Puma as its web server. This means existing material on scaling a modern Rails application will apply. There's a lot of existing knowledge on the web, so we won't dive into too much detail here because tuning and scaling Keygen will ultimately depend on your instance's unique workload.

The most common ways to tune Keygen is through its various concurrency controls. You can tune RAILS_MAX_THREADS and WEB_CONCURRENCY according to your server specs.

• The higher the WEB_CONCURRENCY, the more throughput you will have, at the cost of memory.
• The higher the RAILS_MAX_THREADS, the more throughput you will have, at the cost of CPU.

Aim for WEB_CONCURRENCY to be as high as memory allows. Aim for RAILS_MAX_THREADS to be between 2 and 5, depending on your CPU core count; anything higher and Ruby's GIL will become a bottleneck, and latency will suffer.

In addition, your DB_POOL and REDIS_POOL_SIZE should equal (or exceed) RAILS_MAX_THREADS.