# Bosun — Rails Deployment for Shared, Multi-Tenant Ubuntu Hosts

> Bosun is a `.deb`-packaged CLI for deploying Rails apps on
> [argus-tty](https://github.com/ramlaxmanyadav/argus-tty)-managed Ubuntu hosts. It solves a
> different problem than Capistrano/Mina/Kamal: not "how do I clone, build, and restart" (every tool
> answers that), but "how do several developers, a deployer, and an admin all deploy the same shared
> box without a common root account, without everyone's personal SSH key on the git host, and without
> every developer having standing read access to `DATABASE_URL`/`SECRET_KEY_BASE`."

Three enforced account tiers (developer/deployer/admin, via argus-tty, checked per-subcommand by
`require_role()`), secrets ACL-locked to a single unprivileged `webapp-svc` service account (not the
shared `webapps` group), one git deploy key per app distributed to every admin/deployer instead of N
personal keys, and a deploy pipeline (clone → bundle install → assets:precompile → symlink swap →
restart → health check → automatic rollback → cleanup) with zero new sudo privileges granted beyond
what argus-tty already whitelists.

argus-tty is recommended, not required: without it, bosun falls back to a single-operator
**standalone mode** automatically — no tiers, no separate service account, one account does
everything — see [standalone mode](https://ramlaxmanyadav.github.io/bosun/standalone.html).

## Getting started

- [README](https://github.com/ramlaxmanyadav/bosun/blob/main/README.md): installing (Launchpad PPA
  or `.deb`) and a condensed quick start — the full reference lives in the docs below.
- [llms-full.txt](https://ramlaxmanyadav.github.io/bosun/llms-full.txt): this file plus the complete
  content of the README and every `docs/*.md` file, concatenated into one fetch — for agents that
  prefer a single request over following links.
- [LICENSE](https://github.com/ramlaxmanyadav/bosun/blob/main/LICENSE): MIT.

## Documentation

- [installing](https://ramlaxmanyadav.github.io/bosun/installing.html): Launchpad PPA (recommended,
  `ppa:yadavramlaxman/argus-tty` + `ppa:yadavramlaxman/bosun`) or the standalone `.deb` package,
  install order, verifying the install, and the standalone-mode fallback with no argus-tty.
- [walkthrough](https://ramlaxmanyadav.github.io/bosun/walkthrough.html): the full walkthrough —
  setting up a new app from scratch, every command, real sample output.
- [permissions](https://ramlaxmanyadav.github.io/bosun/permissions.html): who can do what — the
  developer/deployer/admin tier table, and why `shared/.env` is locked tighter than the rest of the
  app tree.
- [provisioning](https://ramlaxmanyadav.github.io/bosun/provisioning.html): everything `bosun add`
  creates on disk — ACLs, `.env`, `deploy.conf`, systemd units, the git deploy key, RVM/gemsets — and
  why.
- [deploy-key](https://ramlaxmanyadav.github.io/bosun/deploy-key.html): the shared, per-app git
  deploy key — one keypair distributed to every admin/deployer account, never developers, never a
  personal key.
- [running-commands](https://ramlaxmanyadav.github.io/bosun/running-commands.html): `bosun run`
  (console/rake/migrations) and `bosun logs` — both load `shared/.env` the same way Puma/Sidekiq do.
- [customizing-deploy](https://ramlaxmanyadav.github.io/bosun/customizing-deploy.html): overriding
  `do-release` with a full script instead of a hook DSL, for one app only.
- [custom-service](https://ramlaxmanyadav.github.io/bosun/custom-service.html):
  adding a third service beyond the built-in Puma+Sidekiq pair (a sneakers/RabbitMQ consumer, Docker
  instead of systemd, anything else) in bosun's own format — the exec-wrapper pattern, the systemd
  unit template, and the one logging convention every bosun-managed worker follows.
- [systemd](https://ramlaxmanyadav.github.io/bosun/systemd.html): exactly what
  `bosun add` generates for Puma/Sidekiq, the shipped reference `.service`/`.socket` samples, and
  optional socket activation.
- [crontab](https://ramlaxmanyadav.github.io/bosun/crontab.html): the
  `/etc/cron.d/<app>` format bosun generates, why scheduled tasks must run as `webapp-svc`, and how to
  verify a job actually ran.
- [ruby-version](https://ramlaxmanyadav.github.io/bosun/ruby-version.html):
  changing an app's Ruby version — the install/deploy sequence, and how old-version cleanup stays safe
  on a host where several apps share one RVM install.
- [standalone](https://ramlaxmanyadav.github.io/bosun/standalone.html): running
  bosun without argus-tty — what single-operator standalone mode changes, the `/etc/bosun.conf`
  persisted-account file, and the security tradeoff it accepts.
- [nginx](https://ramlaxmanyadav.github.io/bosun/nginx.html): reverse-proxying
  to the Puma unix socket (bosun doesn't manage nginx itself).

## Guides

- [Why bosun locks secrets to one service account instead of a shared group or box-wide env](https://ramlaxmanyadav.github.io/bosun/secrets-locked-to-one-service-account.html):
  the ACL model behind `shared/.env`, and why there's no `dotenv-rails` dependency anywhere in the
  stack.
- [Multi-tenant Rails deployment: deploying without root or a personal SSH key](https://ramlaxmanyadav.github.io/bosun/multi-tenant-rails-deployment.html):
  the developer/deployer/admin tier model and the shared per-app git deploy key, explained.
- [A full script override instead of a hook DSL](https://ramlaxmanyadav.github.io/bosun/full-script-override-vs-hooks.html):
  why `do-release.sample` is plain bash you copy and edit, not a plugin system to learn, plus a
  worked example swapping Sidekiq for a RabbitMQ consumer.

## Quick start

```bash
# One time per host:
sudo add-apt-repository ppa:yadavramlaxman/argus-tty && sudo add-apt-repository ppa:yadavramlaxman/bosun
sudo apt update && sudo apt install argus-tty bosun
sudo bosun bootstrap                   # installs RVM multi-user

# One time per app:
sudo bosun add myapp                   # provision /var/www/myapp, a shared deploy key, puma+sidekiq units
vi /var/www/myapp/shared/deploy.conf   # RUBY_VERSION, RUBY_GEMSET, PROJECT_REPO_URL
sudo vi /var/www/myapp/shared/.env     # DATABASE_URL, SECRET_KEY_BASE, RAILS_ENV
bosun install myapp                    # ruby/gemset + OS build deps
bosun setup myapp                      # releases/shared/config tree

# Every deploy after that:
bosun deploy myapp main
```

## Commands

- `sudo bosun add <app-name>` — provision an app (root only).
- `sudo bosun bootstrap` — RVM multi-user install, once per host (root only).
- `bosun install <app-name>` — ruby/gemset + OS build deps (developer/admin).
- `bosun setup <app-name>` — releases/shared/config tree (developer/admin).
- `bosun deploy <app-name> <git-branch>` — the actual deploy, with automatic rollback (deployer/admin).
- `bosun cleanup <app-name>` — prune old releases (deployer/admin; `deploy` also runs this
  automatically).
- `bosun restart <app-name>` — restart puma + sidekiq (deployer/admin).
- `bosun run <rails-args...> <app-name>` — any `rails` command/task, env loaded via `shared/bin/run`
  (developer/admin).
- `bosun logs [-t] <app-name>` — show or follow an app's Rails logs (developer/admin).
- `bosun mode [name]` — view or switch between argus-tty and standalone mode (view: any tier; set:
  root only).
- `bosun version [app-name]` — bosun's own version, RVM's version, and (given an app) its configured
  ruby/gemset — the one subcommand with no role restriction at all, since it exposes nothing
  sensitive.

## Links

- [GitHub repo](https://github.com/ramlaxmanyadav/bosun)
- [argus-tty](https://github.com/ramlaxmanyadav/argus-tty) (recommended — see the standalone doc for running without it)
- [This site's index](https://ramlaxmanyadav.github.io/bosun/)