← Bosun

Walkthrough: setting up a new app from scratch

Every command and real sample output, from a fresh host to a first deploy.

One-time per host (skip if already done; see the README for the Launchpad PPA option):

sudo apt install ./argus-tty_1.0.0_all.deb    # or sudo ./install.sh from a loose checkout, or the PPA (see the README)
  sudo apt install ./bosun_1.0.0_all.deb
  sudo argus-tty status                          # confirm green

  sudo bosun bootstrap                # installs RVM multi-user AND retrofits existing accounts + webapp-svc onto webapps/rvm

One-time per app:

# 1. Admin: provision the app
  sudo bosun add myapp
  # Prints a public key — add it as a read-only Deploy Key on myapp's git
  # repo (see docs/deploy-key.md). Already distributed to every current
  # developer/admin account, so no per-person git access to set up.

  # If the deploying developer has no account yet:
  sudo argus-tty add alice --name "Alice Kumar" --pubkey alice_id_ed25519.pub
  # (they must log out/in if they were already logged in — group membership
  # doesn't apply retroactively to an open session)
  # Since they were just added, backfill their copy of myapp's deploy key:
  sudo bosun add myapp

# 2. Developer: fill in deploy metadata
  ssh alice@host
  vi /var/www/myapp/shared/deploy.conf
  #   RUBY_VERSION=ruby-3.3.3
  #   RUBY_GEMSET=myapp
  #   PROJECT_REPO_URL=git@git.example.com:yourorg/myapp.git
  #   KEEP_LATEST_RELEASE=5

  # 3. Admin: fill in app secrets — shared/.env is root:root 600 (ACL read
  #    grant for webapp-svc only), so a developer/deployer account can't
  #    open it directly even to overwrite it; only an admin's full sudo
  #    covers this (see docs/permissions.md).
  sudo vi /var/www/myapp/shared/.env
  #   DATABASE_URL=postgres://...
  #   SECRET_KEY_BASE=...
  #   RAILS_ENV=production

  # 4. Developer: install this app's Ruby + OS build deps
  #    What this actually does (deployment/install): installs the OS packages
  #    Rails native gems need (nodejs, libmysqlclient-dev, imagemagick, etc. —
  #    sudo apt-get, whitelisted for developers), then `rvm install` +
  #    `rvm use --create` for the RUBY_VERSION@RUBY_GEMSET from step 2's
  #    deploy.conf, then `gem install bundler`. No sudo needed for the RVM
  #    part — multi-user RVM is group-writable. Requires `bosun bootstrap`
  #    (above) to have already run once on this host.
  bosun install myapp
  # [INFO]  Installing OS build dependencies (sudo apt-get — whitelisted for developers)...
  # [INFO]  Installing ruby-3.3.3 (gemset: myapp) via RVM — no sudo needed, multi-user RVM is group-writable...
  # [INFO]  Dependencies installed for 'myapp': ruby-3.3.3@myapp + bundler.
  bosun version myapp   # sanity-check: confirms the ruby/gemset deploy.conf actually has on file

  # 5. Developer: set up the shared config tree — run from a checkout of the
  #    APP's own repo (puma.rb/secret.yml templates are copied from ./ ).
  #    What this actually does (deployment/setup): creates releases/shared/
  #    config/log/tmp under /var/www/myapp, writes shared/.ruby-version +
  #    .ruby-gemset (so RVM's cd-hook auto-selects the right ruby the moment
  #    anyone `cd`s into current/), and copies ./puma.rb + ./secret.yml from
  #    the repo checkout you're running it from into shared/config/. Idempotent
  #    — safe to re-run; it never overwrites a database.yml/sidekiq.yml/
  #    secret.yml that already has real content in it, so a second run after
  #    you've filled those in won't blow your edits away.
  git clone git@git.example.com:yourorg/myapp.git /tmp/myapp-config
  cd /tmp/myapp-config
  bosun setup myapp
  # Project directory setup started for 'myapp'...
  # [WARN]  ./secret.yml not found in /tmp/myapp-config — skipping (expected to come from the app repo checkout).
  # Please fill in /var/www/myapp/shared/config/database.yml/sidekiq.yml/sidekiq.rb for 'myapp'.
  # App secrets (DATABASE_URL, SECRET_KEY_BASE, etc.) belong in /var/www/myapp/shared/.env, not in a config file.
  # [INFO]  Setup complete for 'myapp'.
  vi /var/www/myapp/shared/config/database.yml
  vi /var/www/myapp/shared/config/sidekiq.yml
  vi /var/www/myapp/shared/config/sidekiq.rb

  # 6. Developer: first deploy
  bosun deploy myapp main

Verify:

sudo systemctl status puma-myapp sidekiq-myapp
  sudo journalctl -u puma-myapp -n 50

Need a console or to run a migration by hand afterward? Don't invoke bundle/rails directly — use bosun run so shared/.env is actually loaded (see docs/running-commands.md):

bosun run console myapp
  bosun run db:migrate myapp

Steps 1–5 are one-time per app. Every deploy after that is just step 6 again: bosun deploy myapp <branch>. Want to prune old releases outside of a deploy? bosun cleanup myapp (runs automatically at the end of every deploy anyway).