deploykit_docs

docs Servers

Servers

Connect local and remote Docker hosts, manage the SSH keys DeployKit uses to reach them, and keep their disks clean.

Server Types

Local Server

The machine where DeployKit itself runs, driven through the local Docker socket. Register it with Add Local Server on the Servers page. Only one local server can exist.

Remote Server

Any Linux host DeployKit can reach over SSH. Applications, databases and stacks can be deployed to it; DeployKit runs the Docker commands there through an SSH key from the SSH Keys catalogue.

Servers are instance-wide infrastructure: adding, editing, removing servers and installing Docker require the global Admin role. Operators can run health checks.

SSH Keys

Since v0.3.0, SSH keys live in their own catalogue instead of being pasted into each server. Open SSH Keys in the sidebar (Admin only) and click Add SSH Key. You can either:

  • Generate a new key pair — RSA 4096 or ED25519 — directly in the dialog
  • Import one of your own keys by pasting its private key (OpenSSH or PEM); the public key and SHA256 fingerprint are derived from it automatically
  • Give the key a name and an optional description so you can tell keys apart

Copy the public key into the remote user's ~/.ssh/authorized_keys, then pick the key when you add the server. One key can be shared by several servers.

bash
# On the remote server, as the user DeployKit will connect with
mkdir -p ~/.ssh && chmod 700 ~/.ssh
echo "ssh-ed25519 AAAA... deploykit" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
  • The private key is shown only once, when you create it. It is encrypted at rest with AES-256-GCM and never returned by the API again — download it from the dialog if you want a copy
  • Only RSA and ED25519 keys are supported. Passphrase-protected keys are rejected, because DeployKit cannot unlock them
  • A key that is still attached to a server cannot be deleted; the error lists the servers to detach first
  • Creating, renaming and deleting keys is recorded in the audit log

Upgrading from v0.2 or earlier: v0.3.0 changed how remote servers are connected. On the first start after upgrading, the database migration moves each server's stored private key into the SSH Keys catalogue as Migrated — <server name> and attaches it to that server. A server whose key could not be migrated shows No SSH key and cannot be reached until it has one: create a key, then remove and re-add the server with it (see Removing a Server below for what happens to its services).

Adding a Remote Server

On the Servers page click Add Server and fill in:

  • Server Name — a friendly identifier, e.g. production-1
  • Host / IP — IP address or hostname of the server
  • SSH Port — defaults to 22
  • Username — defaults to root
  • SSH Key — required; chosen from the SSH Keys catalogue (create one first if the list is empty)

What the Remote Server Needs

  • SSH reachable from the DeployKit host, with the key's public half in authorized_keys
  • git — repositories are cloned on the remote server itself
  • Docker — or let DeployKit install it for you (see below)
  • Either the root user, or a user that can run sudo without a password prompt: for any user other than root, DeployKit prefixes its Docker commands with sudo
  • Enough disk for images and build contexts; builds run in /tmp/deploykit-builds and are cleaned up afterwards

Health Checks and Server Info

Click Check health on a server card to test the SSH connection and Docker. The server is marked connected (SSH and Docker work), disconnected (SSH works, Docker missing) or error (SSH failed). The card then shows the OS, CPU cores, total RAM and disk, the number of containers, the Docker version and when the server was last checked, plus the applications and databases deployed on it. Health checks run when you trigger them; there is no background polling of servers.

Docker Auto-Install

If the health check finds that SSH works but Docker is missing, the card offers Install Docker. DeployKit runs the official install script from get.docker.com, enables and starts the Docker service, and adds a non-root user to the docker group. It needs root or sudo access and can take a few minutes. Run a health check afterwards to verify.

Remote Deployments

When an application targets a remote server, the deploy worker clones the repository on that machine over SSH, builds the image there with docker build, starts the container and removes the build directory. Logs are streamed back to the dashboard in real time. Differences from local deployments:

  • Remote builds always use the application's Dockerfile (Dockerfile path setting); Nixpacks and Buildpacks builds run only on the local server
  • The Trivy vulnerability scan is skipped, because the image lives on the remote daemon
  • DeployKit does not install a reverse proxy on remote servers — containers get the same Traefik labels, but routing domains to them needs a Traefik instance on that host
  • Game servers run only on the local server

Image Cleanup

Every deployment leaves a deploykit/* image behind. Every night at 03:00, DeployKit prunes them on all servers, keeping the last 3 successful deployment images per app so rollbacks keep working. Admins can also run it on demand with Clean images on the Servers page, choosing how many images to keep per app (1–20) and optionally doing a dry run first to preview what would be removed.

Removing a Server

Removing a server from DeployKit does not stop or delete what is running on it. Applications, databases, stacks and game servers that pointed to it are kept, but lose their server assignment. The SSH key stays in the catalogue and can be deleted separately once no server uses it.

Firewall warning: Docker bypasses ufw. Any port DeployKit publishes on a host — a database with an external port, an application host port, a game server port — is reachable from the internet even if ufw status says it is blocked, because Docker inserts its own iptables rules ahead of ufw's. DeployKit does not manage ufw or iptables. Filter traffic in your cloud provider's firewall (Hetzner Cloud Firewall, AWS Security Groups…), or add rules to the DOCKER-USER chain (for example with ufw-docker). Do not disable Docker's iptables integration — it breaks container networking.