onboard

Guide the user through getting started with Bosun and help them understand how it works. Use resource files for deep dives into specific topics.

What is Bosun?

Bosun is a single-binary CLI tool that brings GitOps workflows to homelab Docker Compose deployments. Write short manifest files, bosun generates Docker Compose + Traefik + Gatus configs. Push to git, bosun reconciles your server automatically. No Kubernetes required.

The pitch: Write a 10-line manifest, get a fully configured service with routing, monitoring, health checks, and compose orchestration -- all deployed automatically when you push to git.

Nautical Terminology

Everything uses nautical/Below Deck naming:

Term	Meaning
Yacht	Your server running Docker Compose
Crew	Your containers
Captain	GitHub (gives orders via webhooks)
Manifest	Service definitions (what to deploy)
Provisions	Reusable config templates (how to deploy)
Radio	Webhook/tunnel for receiving push events
Bosun	The CLI tool itself (receives orders, deploys crew)

Prerequisites

Before setting up Bosun, ensure the following are installed:

• Docker + Docker Compose v2 -- docker compose version to verify
• Git -- for repository operations
• SOPS + Age -- for secret encryption (age-keygen to generate keys, sops CLI for encryption)
• Go 1.25+ -- only if building from source
• Linux or macOS -- tested on Unraid, Debian, Ubuntu, macOS
• Tailscale (optional) -- for webhook tunnel via bosun radio

Installation

Pick one method:

# Quick install (recommended) -- downloads, verifies checksum, installs to /usr/local/bin
curl -fsSL https://raw.githubusercontent.com/cameronsjo/bosun/main/scripts/install.sh | bash

# Via Go
go install github.com/cameronsjo/bosun/cmd/bosun@latest

# From source
git clone https://github.com/cameronsjo/bosun.git
cd bosun && make build    # output at build/bosun

Update an existing install:

bosun update              # Update to latest release
bosun update --check      # Check for updates without installing

Initial Setup

1. Generate an Age encryption key (if not already done):

   age-keygen -o ~/.config/sops/age/keys.txt
   

2. Create .sops.yaml in the project root with the public key from step 1.

3. Initialize the project:

   bosun init              # Interactive setup wizard
   bosun init --yes        # Non-interactive (for CI/CD)
   bosun init my-homelab   # Initialize in a new directory
   

4. Run pre-flight checks:

   bosun doctor
   

   Validates Docker, Git, SOPS, Age key, manifest directory, and webhook status.

5. Start your services:

   bosun yacht up
   

Command Groups at a Glance

Group	Commands	Purpose
Setup	init, doctor, update	Project creation, health checks, updates
Yacht	yacht up/down/restart/status	Manage Docker Compose stacks
Crew	crew list/logs/inspect/restart	Manage individual containers
Manifest	provision, provisions, create, lint, render, chart	Build and validate service configs
GitOps	daemon, reconcile, trigger, drift	Automated deployment pipeline
Radio	radio test/status	Webhook and tunnel connectivity
Alerts	alert status/test	Deploy notification testing and status
Diagnostics	status, log, doctor, validate	Health monitoring and debugging
Emergency	mayday, overboard, restore	Error triage, rollback, force-remove, backup restore
Utilities	update, completion	Self-update, shell completions

For complete command details with all flags and examples, see @resources/commands.md.

Core Workflow

For manual deployments:

bosun provision mystack        # Render manifest -> compose/traefik/gatus files
bosun provision mystack -n     # Preview without writing (dry run)
bosun yacht up                 # Start/update services
bosun crew list                # Verify containers are running
bosun drift --live             # Check for drift between config and running state

For automated GitOps:

bosun daemon                   # Run long-lived daemon (webhook + polling)
# ... push changes to git ...
# Bosun automatically: pulls repo -> decrypts secrets -> templates configs -> deploys
bosun trigger                  # Or manually trigger reconciliation
bosun drift                    # Check for drift between deploys

For full GitOps setup details, see @resources/gitops.md.

Writing Service Manifests

A manifest describes what to deploy. Provisions describe how. Bosun renders both into Docker Compose, Traefik, and Gatus configs.

Minimal example (a web app with routing and monitoring):

# manifest/services/myapp.yml
name: myapp
provisions: [container, reverse-proxy, monitoring]
config:
  image: ghcr.io/org/myapp:latest
  port: 3000
  subdomain: myapp
  domain: example.com

Full example (web app with Postgres sidecar, health checks, and homepage entry):

name: norish
provisions: [container, healthcheck, homepage, reverse-proxy, monitoring]
config:
  image: ghcr.io/norishapp/norish:latest
  port: 3000
  subdomain: recipes
  domain: example.com
  group: Apps
  icon: mdi-food
  description: Recipe manager
services:
  postgres:
    version: 17
    db: norish
    db_password: "{{ $secrets.apps.norish.db_password }}"

For the complete manifest schema, variable interpolation rules, and provision types, see @resources/manifests.md.

Configuration

Bosun finds its project root by searching upward from the current directory for:

• bosun.yaml or bosun.yml config file
• bosun/ directory with docker-compose.yml
• manifest/ or manifests/ directory

For the full config file reference and environment variables, see @resources/configuration.md.

Common Tasks

Task	Command
Start all services	bosun yacht up
Start specific services	bosun yacht up traefik redis
Check container health	bosun crew list
View container logs	bosun crew logs <name> -f
Preview rendered config	bosun provision mystack -n
Show diff before applying	bosun provision mystack -d
Run one-shot deploy	bosun reconcile
Dry-run deploy	bosun reconcile -n
Check for drift	bosun drift --live
View recent errors	bosun mayday
Rollback to snapshot	bosun mayday -r interactive
Force-remove stuck container	bosun overboard <name>
Scaffold new service	bosun create webapp myapp
Validate manifests	bosun lint
Check system health	bosun status
Restore from backup	bosun restore or bosun restore -l
Test alert providers	bosun alert test
Set up shell completions	bosun completion bash | sudo tee /etc/bash_completion.d/bosun

Troubleshooting Quick Reference

Problem	Fix
"project root not found"	Ensure you're inside a bosun project, or use bosun --root /path
"connect to docker"	Check Docker is running (docker ps), check socket permissions
"sops decrypt failed"	Verify sops --version, check age key at ~/.config/sops/age/keys.txt
"docker compose: command not found"	Install Docker Compose v2: docker compose version
SSH failures (remote deploy)	Test ssh user@host exit, check ssh-add -l

Run bosun doctor to diagnose most setup issues.

Pirate Mode (Easter Egg)

All commands have nautical aliases. Run bosun yarr to see them:

Command	Alias
yacht	hoist
crew	scallywags
provision	plunder, loot, forge
radio	parrot
status	bridge
doctor	checkup
mayday	mutiny
overboard	plank
init	christen

Key Project Files

When working on Bosun itself:

Path	Purpose
cmd/bosun/main.go	CLI entry point
internal/cmd/	Cobra command definitions (one file per command)
internal/manifest/	YAML rendering engine for service manifests
internal/reconcile/	GitOps engine (clone, decrypt, template, deploy)
internal/docker/	Docker SDK wrapper
internal/config/	Configuration loading and project discovery
Makefile	Build, test, lint, CI targets (make help for full list)

Development

make build              # Build binary -> build/bosun
make test               # Run tests
make test-cover         # Run tests with coverage report
make lint               # Run linter (requires golangci-lint)
make ci                 # Run full CI pipeline locally via Dagger
make run ARGS="doctor"  # Run without building

Resource Files

For deeper information on specific topics:

• @resources/commands.md -- Every CLI command with flags, examples, and behavior
• @resources/manifests.md -- Manifest system: schemas, provisions, stacks, interpolation
• @resources/gitops.md -- GitOps pipeline: daemon, reconciliation, webhooks, drift
• @resources/configuration.md -- Config file reference, environment variables, project structure