Quickstart

Install on your server

Use a Linux host (x86_64 or arm64) with Docker running and systemd. Run this on the server; the installer configures the CLI for the user who runs it:

curl -fsSL https://oddk.dev/install | sh

See Install for version pinning and updates. Run the remaining oddk commands on this server.

Create an instance

Four CPUs, 8 GB of RAM, listening on 5432. The image is pulled automatically if it isn’t already local.

oddk create --name app --version 17 --port 5432 --cpu 4 --ram 8

The command blocks until Postgres actually accepts connections. If readiness is never reached, oddk rolls back the container and volume rather than leaving you a broken instance.

Get a connection string

The password is generated at create time and encrypted at rest.

oddk instance get-postgres-password app --conn
# postgresql://postgres:••••••••@10.88.0.1:5432/postgres

Provision a database and its owner

oddk instance create-db app --database billing --username billing

This creates both in one step and prints the generated password and connection string. If database creation fails, the just-created user is rolled back.

Connect from your laptop

The connection string’s 10.88.0.1 address belongs to the server’s local Docker bridge. From your laptop, open an SSH tunnel, replacing user@db01 with your SSH login and server address:

ssh -N -o ExitOnForwardFailure=yes \
  -L 127.0.0.1:15432:10.88.0.1:5432 user@db01

Leave that terminal open. In another local terminal, connect with psql:

psql -h 127.0.0.1 -p 15432 -U billing -d billing -W

Enter the password printed by create-db. In a graphical database client, use the same host, port, database and user. The tunnel uses local port 15432 so it can coexist with a local Postgres server on 5432.

Protect it

On the server, enable the nightly snapshot:

oddk snapshot setup-cron --utc-hour 3          # nightly, whole deployment

A local snapshot is lost with the server. Before relying on the schedule:

1. Configure and test offsite copies.
2. Back up the master key separately.
3. Configure and test a notification channel.

Then check coverage and address any findings:

oddk checklist

See Snapshots & recovery for the recovery procedure, or Tuning to adjust your instance’s parameters.