Installation

Install the CLI on the developer machine, create a server profile, then initialize the VPS base stack.

Requirements

The VPS needs:

• Linux and SSH access;
• Docker Engine with the Compose plugin;
• rsync;
• a deployment user allowed to run Docker without sudo.

The developer machine needs Go 1.26.5 or newer, Git, Docker, SSH, rsync, and Bash. Applications with encrypted secrets also need SOPS and access to the configured key; the current templates use age recipients.

Docker group access

Membership in the Docker group effectively grants root-level access to the server. Only grant it to a trusted deployment user.

Prepare the server

Create a deployment user, install its SSH key, and add it to the Docker group. Then verify access from the developer machine:

ssh dockiy@your-server docker compose version

Use an SSH config alias for custom keys, ports, or jump hosts.

Install the CLI

Build the current CLI from the DockIY repository:

git clone https://codeberg.org/chris-paganon/dockiy.git
cd dockiy/cli
go install ./cmd/dockiy
dockiy --help

Ensure Go's binary directory is on PATH.

Create the server profile

Run the guided setup:

dockiy setup
dockiy config validate

On Linux, the config defaults to ~/.config/dockiy/config.yml. Use --config or DOCKIFY_CONFIG to select another path. Setup refuses to overwrite an existing file unless --force is used.

A minimal config is:

version: 1
default_server: personal
servers:
  personal:
    ssh: dockiy@your-server

Omitted settings use these defaults:

• remote path: dockiy;
• build platform: linux/amd64;
• local registry tunnel port: 5500;
• VPS registry port: 5000.

An optional dockiy.config.yml in the current directory can override the global config for that checkout. Profiles and nested values are merged by key.

For automation, use:

dockiy setup --non-interactive --server personal --ssh dockiy@your-server

Add flags for any non-default values.

Initialize the base stack

Run the interactive initializer from the directory where the local dockiy/ infrastructure repository should live:

dockiy server init
dockiy server status

The initializer asks for the ACME email, public service hostnames, and initial Umami, Beszel, and Dozzle accounts. It generates database and application secrets when omitted. For automation, add --non-interactive and the required flags shown by dockiy server init --help. Secret flags may be visible in shell history and process listings.

Initialization clones the pinned base stack, keeps it as the local infrastructure repository, uploads its manifest-listed files, starts seven services, configures the initial Umami and Beszel accounts, and records the successful operation on the VPS. A successful initialization is one-shot.

Edit and commit infrastructure changes in the local repository. Apply them with:

dockiy server update
dockiy server update --pull

update syncs and reconciles the stack. Images are pulled only with --pull. The CLI has no server reset command; reset the VPS manually when needed.