API Overview

This API provides endpoints for managing game deployments and releases:

Deployment Management

• /preDeploy/:game/:env/:version - Prepares new build directory for deployment.
• /postDeploy/:game/:env/:version - Finalizes deployment, creates symlinks, and manages build info.
• /deployments/:game/:env - Lists all deployments for a specific game environment.
• /deployments/:game/:env/:version - Gets info about a specific deployment.

Release Management

• /publish/:game/:platform/:buildKey? - Publishes a new build as a release.
• /rollback/:game/:platform/:buildKey? - Rolls back to a previous release.
• /releases/:game/:platform - Lists all releases for a game/platform.
• /releases/:game/:platform/current - Gets info about the current release.
• /releases/:game/:platform/:buildKey - Gets info about a specific release.

Authentication

• Bearer token authentication can be enabled/disabled via environment variables.
• When enabled, all requests must include a valid bearer token.

File Structure

• Stores each game build in its own directory with build info and assets.
• Manages releases through releases.json file and symlinks.
• Maintains deployment history and release states.

How to Use

The deployment workflow consists of three main phases:

1. Deployment Phase

1. Prepare for deployment

   GET /preDeploy/:game/:env/:version

   • Creates a new directory for your build
   • Returns the newBuildDir path for game files
   • Example: /preDeploy/my-game/staging/42

2. Upload game files

   • Copy game build files (index.html, assets, etc.) to the newBuildDir
   • Include build_info.json with version, git info, and build timestamp

3. Finalize deployment

   GET /postDeploy/:game/:env/:version

   • Validates the deployment
   • Creates latest symlink
   • Manages old deployments cleanup
   • Example: /postDeploy/my-game/staging/42

2. Release Phase

1. Publish the build

   GET /publish/:game/:platform/:buildKey

   • Publishes a deployed build as a release
   • Creates necessary symlinks and release info
   • Example: /publish/my-game/facebook/staging-42

2. Verify the release

   GET /releases/:game/:platform/current

   • Confirms the current active release
   • Example: /releases/my-game/facebook/current

3. Rollback Phase

1. Check available releases

   GET /releases/:game/:platform

   • Lists all available releases with their info
   • Shows release history for rollback selection
   • Example: /releases/my-game/facebook

2. Perform rollback

   GET /rollback/:game/:platform/:buildKey

   • Reverts to a specific previous release
   • Updates the current release pointer
   • Updates necessary symlinks
   • Example: /rollback/my-game/facebook/staging-41

   Note: Omitting buildKey automatically rolls back to the previous release.

3. Verify rollback

   GET /releases/:game/:platform/current

   • Confirms the active release after rollback
   • Example: /releases/my-game/facebook/current

Additional Operations

• List all deployments: GET /deployments/:game/:env
• Check deployment details: GET /deployments/:game/:env/:version
• View release history: GET /releases/:game/:platform

Important Notes

• Each deployment requires build_info.json and index.html files
• The system maintains complete deployment and release history
• Rollback operations are reversible
• Authentication requires a Bearer token when enabled

CLI and Client Library

This repo ships a CLI and a Node-only TypeScript client library.

Install

npm install -g @vforsh/rmatic

npm install @vforsh/rmatic-client

Configuration

CLI config precedence: flags > env vars > config file.

• RMATIC_BASE_URL
• RMATIC_TOKEN

Config file path:

$XDG_CONFIG_HOME/rmatic/config.json
# or ~/.config/rmatic/config.json

CLI Examples

rmatic --base-url https://… --token $RMATIC_TOKEN health
rmatic config init --interactive
rmatic config
rmatic publish papa-cherry-2 vk master-21
rmatic releases list papa-cherry-2 vk --plain
rmatic rollback papa-cherry-2 vk --force
rmatic deploy pre papa-cherry-2 staging 42
rmatic deploy post papa-cherry-2 staging 42
rmatic deployments list papa-cherry-2 staging

Service Deployment

This repo is deployed to a Dokku remote. Deploys are git pushes that trigger a Docker build on the server.

Prerequisites

• Dokku is installed and reachable over SSH: follow Dokku’s Getting Started / Installation guide and verify you can run ssh dokku@your-host dokku version.
• Your SSH key is authorized: your local machine can SSH to the Dokku host as the Dokku user.
• Domains + DNS: any domains you add via domains:add should have DNS records pointing at the server (see Dokku docs: Domain Configuration).
• Reverse proxy / TLS: configure your web server (e.g. Caddy/Nginx) to proxy to the app’s port (see “Server Setup (Reverse Proxy)” below).

Initial Dokku app setup (scripts/dokku-app-setup.ts)

This repo includes a one-time bootstrap script to create/configure the Dokku app on a fresh server:

• Checks Dokku is reachable: verifies SSH connectivity and that Dokku is installed.
• Creates the Dokku app: apps:create release-o-matic (skips if it already exists).
• Configures domains: clears existing domains and adds the configured domains.
• Configures storage mounts: mounts host directories into the container. If STORAGE_MOUNTS is set, the script will auto-install dokku-storage if needed.
• Configures local git remote: adds a dokku remote pointing at dokku@host:app.

Before running it, edit the constants at the top of scripts/dokku-app-setup.ts:

• DOKKU_HOST / DOKKU_USER: where Dokku is running (and which SSH user to use).
• APP_NAME / DOMAINS: Dokku app name and domains to attach.
• STORAGE_MOUNTS: array of "host_dir:container_dir" mounts (example: "/var/www/html:/app/data").
• GIT_REMOTE_NAME: local git remote name to create (defaults to dokku).

Run the setup script:

bun scripts/dokku-app-setup.ts

How to deploy

1. Make sure the dokku remote exists and points to the server:

   git remote -v

2. Deploy using the helper script (sets build metadata and pushes):

   bun run deploy

   This sets:

   • BUILD_VERSION to the current git commit short hash
   • DEPLOYED_AT to an ISO timestamp

   You can override these with env vars:

   BUILD_VERSION=custom DEPLOYED_AT=2025-12-28T20:00:00Z bun run deploy

How deploys work

• Dokku builds the app using the Dockerfile.
• The Docker image is based on oven/bun:1.3.5.
• Dependencies are installed via bun install --frozen-lockfile using bun.lock.
• The container starts with bun run start (see package.json), which currently runs the server in hot mode.
• Healthchecks verify the app is listening on the configured port before routing traffic.
• The /health endpoint returns buildVersion and deployedAt when set.

Server Setup (Reverse Proxy)

You will need to set up a reverse proxy with your server software to forward requests to the port where the app is running.

I use Caddy as a web server, here is the section of my Caddyfile (by default it is located at /etc/caddy/Caddyfile):

your-domain.com {
	# Set this path to your site's directory.
	root * /var/www/html

	# ...more settings...

	# path relative to the root
	handle_path /papa-cherry-2/releases* {
		# notice that we have to specify the port here, use the same port as in the Bun server config
		reverse_proxy localhost:4000
	}
}

Testing

Use bun run test instead of bun test. Because bun test uses the Bun test runner but we use vitest for the current project.