Bosun

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:

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.24+ -- 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

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

Troubleshooting Quick Reference

Run bosun doctor to diagnose most setup issues.

Pirate Mode (Easter Egg)

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

Key Project Files

When working on Bosun itself:

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