Shipyard

Shipyard is a terminal UI for managing Docker containers across remote machines over SSH.

It is designed for a simple homelab workflow:

• see containers across multiple hosts in one view
• filter by host
• start, stop, and restart containers
• open live logs for any selected container
• deploy a local docker-compose.yml and optional .env to one host

Shipyard uses your local ssh and scp commands instead of the Docker Remote API, so it follows the same SSH behavior that already works in your terminal.

Quick Start

Clone the repo, then install the binary:

./install.sh

Then launch it from anywhere:

shipyard

If you already have a config file in a custom location:

shipyard --config /path/to/shipyard.yaml

Features

• Aggregated container overview across all configured hosts
• Host filtering by configured hostname/name
• Running-only toggle or all-containers view
• Start, stop, and restart actions
• Live container logs with Enter
• Compose bundle deployment to a selected host
• First-run onboarding wizard when no config exists
• SnapVault-style text-first TUI with obvious selection markers

Requirements

• Go 1.24+
• ssh and scp available on the local machine
• SSH access to the remote hosts
• Docker installed on the remote hosts
• docker compose available on the remote hosts

First Run

If no config exists, Shipyard starts in a setup wizard.

By default Shipyard uses:

• ./shipyard.yaml when a config exists in the current working directory
• ~/.config/shipyard/shipyard.yaml otherwise

The wizard lets you:

• enter a host name
• enter an SSH address
• optionally enter a Tailscale address
• enter an SSH user
• set a deploy path such as ~/docker
• test the SSH/Docker connection
• add multiple hosts
• save the config and continue into the main app

Run it with:

shipyard

To force Tailscale addresses on launch:

shipyard --tailscale

If you prefer to prepare a config manually, you can still copy and edit the example:

cp shipyard.example.yaml shipyard.yaml
shipyard shipyard.yaml

Config

Example config: shipyard.example.yaml

Each host can optionally define:

tailscale_address: 100.x.y.z

When present, Shipyard tries the normal address first and automatically falls back to tailscale_address if SSH/SCP cannot connect. Use --tailscale to force Tailscale routing from startup.

The default deploy base is:

~/docker

That is usually a better choice on Raspberry Pis than /opt/... because it is writable by the SSH user without extra setup.

Running

Install the binary:

./install.sh

Run tests:

go test ./...

Screens

Overview:

• shows containers across every configured host
• filters by host with h / l
• opens live logs with Enter
• starts, stops, and restarts the selected container

Deploy:

• selects a target host
• accepts a project name
• accepts a local absolute path to docker-compose.yml
• accepts an optional local absolute path to .env
• uploads files and runs docker compose up -d

Logs:

• opens from the overview with Enter
• follows live container logs
• returns to the overview with Esc or b

Keyboard

Global:

• 1 overview
• 2 deploy
• q quit
• ctrl+c quit

Overview:

• j / k or ↑ / ↓ move selection
• h / l filter hosts
• a toggle running-only vs all containers
• Enter open live logs
• s start selected container
• x stop selected container
• R restart selected container
• y / n confirm or cancel actions

Deploy:

• tab / shift+tab or ↑ / ↓ move between fields
• h / l or ← / → change the selected host
• Enter advance or activate the focused action
• ctrl+s or d deploy

Logs:

• Esc or b return to the overview

Setup:

• tab / shift+tab or ↑ / ↓ move between fields and actions
• Enter activate the focused action

Deployment Behavior

Shipyard uploads:

• docker-compose.yml
• .env if provided

Then it runs:

docker compose --project-name <project-name> -f docker-compose.yml --env-file .env up -d

If no .env is provided, the --env-file flag is omitted.

By default projects are written to:

~/docker/<project-name>

Notes

• Host display order uses hostname, then name, then address
• Shipyard writes and reads shipyard.yaml directly
• Connection testing in setup verifies SSH access and Docker visibility
• The current deploy flow updates files in place; it does not keep deploy history