Deploy with drim CLI

What is drim?

drim is a CLI tool for deploying Kaneo. It generates your docker-compose.yml, Caddyfile and .env, installs Docker if it is missing, and brings the stack up, so a fresh server goes from nothing to a running instance in one command. It suits straightforward deployments. If you need a custom topology, extra services, or your own reverse proxy, Docker Compose gives you more control.

Installation

Install Docker and Docker Compose using your operating system’s signed packages before running setup. Then install the fixed drim v0.1.15 release using the release-asset SHA-256 checksums below. The download is saved to a temporary file and verified before it is made executable; it does not run an installation script.

(
  set -eu
  case "$(uname -s)-$(uname -m)" in
    Linux-x86_64)
      drim_asset=drim_Linux_x86_64
      drim_sha256=1961180bd6972e34c6ce9077cedc2524795d9fa717001e1bdec9e36817ca44a8 ;;
    Linux-aarch64|Linux-arm64)
      drim_asset=drim_Linux_arm64
      drim_sha256=58ddb9ed25491c2593f9f6ac3dc27741df75d4f7f05ef9338ace86c6d5aa42a9 ;;
    Darwin-x86_64)
      drim_asset=drim_Darwin_x86_64
      drim_sha256=2019ea560f62f5788c521f070013db5e7fa058ea01b2f2eb7cdbe77e5dae71cb ;;
    Darwin-arm64)
      drim_asset=drim_Darwin_arm64
      drim_sha256=58f353ca36067756ef7796ac79cfddbc4ef9568e051295b8b464782b496b76ab ;;
    *) echo "Unsupported platform; use a supported Linux or macOS system." >&2; exit 1 ;;
  esac
  drim_tmp=$(mktemp -d)
  trap 'rm -rf "$drim_tmp"' EXIT HUP INT TERM
  cd "$drim_tmp"
  curl --fail --show-error --silent --location \
    --proto '=https' --proto-redir '=https' --tlsv1.2 \
    "https://github.com/usekaneo/drim/releases/download/v0.1.15/$drim_asset" \
    --output drim
  if command -v sha256sum >/dev/null 2>&1; then
    printf '%s  drim\n' "$drim_sha256" | sha256sum -c -
  else
    printf '%s  drim\n' "$drim_sha256" | shasum -a 256 -c -
  fi
  mkdir -p "$HOME/.local/bin"
  install -m 755 drim "$HOME/.local/bin/drim"
)

Add ~/.local/bin to your shell’s PATH, or use ~/.local/bin/drim in place of drim below. WSL uses the Linux asset matching its architecture. Stop on a checksum mismatch; do not replace the expected checksum with one supplied by the failed download. These fixed digests pin the published bytes, not a claim that the release was independently audited. When updating drim, select a release and update its expected digest together.

Quick start

Interactive

drim setup

You are asked whether to use the bundled Caddy reverse proxy, and for a domain. Leave the domain empty for a local deployment, reachable at http://localhost, or http://localhost:5173 when you skip the reverse proxy.

Non-interactive

Pass the configuration as flags to skip the prompts, which is what you want in a script or over SSH without a terminal:

drim setup --domain=kaneo.example.com
drim setup --no-reverse-proxy

Point your domain’s DNS A record at the server before running setup. Caddy requests a certificate immediately, and that only succeeds once the record resolves.

Commands

drim setup       # Deploy Kaneo
drim start       # Start services
drim stop        # Stop services
drim restart     # Restart services
drim upgrade     # Pull the latest Kaneo images and restart
drim configure   # Edit .env, then apply the changes
drim uninstall   # Remove Kaneo

Run these from the directory holding your docker-compose.yml. drim tells you when it cannot find a deployment there. drim restart restarts the containers. Because services read configuration through env_file, a plain restart reuses the environment a container was created with, so use drim restart --recreate to recreate containers and pick up .env changes. drim configure already does this for you.

What gets installed

PostgreSQL 16, the database
Kaneo, the API and web app in a single container
Caddy, the reverse proxy with automatic HTTPS, unless you pass --no-reverse-proxy

Services run with health checks and restart automatically unless explicitly stopped. PostgreSQL is only reachable on the internal Docker network, never published to the host.

Configuration

drim configure

This opens .env in $EDITOR (or nano). After saving, drim offers to apply the changes, which recreates the containers so the new values take effect. drim setup writes the variables Kaneo requires. Optional features are enabled by adding their variables, for example:

# GitHub sign-in
GITHUB_OAUTH_CLIENT_ID=your_client_id
GITHUB_OAUTH_CLIENT_SECRET=your_client_secret

# Email
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=you@example.com
SMTP_PASSWORD=your-password
SMTP_FROM=you@example.com

# Redis pub/sub, for running more than one API replica
REDIS_URL=redis://your-redis-host:6379

See environment variables for the full list.

Requirements

Docker 20.10+ and Docker Compose V2
2GB RAM and 10GB disk
A public DNS record, for production deployments

drim installs Docker automatically on supported Linux distributions. When it does, it also adds your user to the docker group and stops, because group membership only applies to a new login session. Log out, log back in, and run drim setup again. If Docker is already installed but you are not in the docker group, setup tells you so before writing any files, along with the command to fix it:

sudo usermod -aG docker $USER

Upgrading

drim upgrade

Back up your database, files, and configuration first. This pulls the selected images and recreates changed services. Data volumes are retained, but the API can migrate the database when it starts. See Upgrade Kaneo for checks and recovery. To update drim itself, repeat the verified installation procedure with a newly reviewed release and its fixed checksum. The built-in updater follows the latest release and is not part of this pinned installation procedure.

Deployments created before Kaneo moved to a single container still run the older two-image layout, and drim upgrade does not rewrite an existing docker-compose.yml. See migrating to drim to move to the current layout.

Building from source

git clone https://github.com/usekaneo/drim.git
cd drim
git checkout --detach f1e404916304699404ca06e9c94b3cf9124b878f
# Review this fixed source revision and its dependencies before building.
go build -mod=readonly -o drim .

make build-all cross-compiles for every supported platform.

Install

Configure

Sign-in providers

Keep it running

Migrate a deployment

Deploy with drim CLI

What is drim?

Installation

Quick start

Interactive

Non-interactive

Commands

What gets installed

Configuration

Requirements

Upgrading

Building from source

Getting help

​What is drim?

​Installation

​Quick start

​Interactive

​Non-interactive

​Commands

​What gets installed

​Configuration

​Requirements

​Upgrading

​Building from source

​Getting help

What is drim?

Installation

Quick start

Interactive

Non-interactive

Commands

What gets installed

Configuration

Requirements

Upgrading

Building from source

Getting help