Skip to main content

Local Development and Sandbox (Vagrant)

This page covers:

  • local development (Docker) from your machine
  • a Vagrant sandbox that runs a full “fresh install” flow in a disposable VM (useful before touching a real server)

Production server install is documented separately in Production Install Runbook.

Local development (Docker)​

1) Generate env (once per checkout / after env changes)​

./infra.sh env generate
./infra.sh env check

2) Start services​

From the repo root:

./infra.sh list
./infra.sh up <project>
./infra.sh logs <project>
./infra.sh status <project>

From inside a specific project folder (preferred when working on that service), use its run.sh if present:

./run.sh help
./run.sh up
./run.sh logs

3) Stop / reset​

./infra.sh down <project>
./infra.sh clean <project>        # add --data to wipe data

Sandbox (Vagrant + VirtualBox)​

The sandbox provisions a local Debian VM and runs bootstrap + deploy against it, to validate the remote install flow safely.

What it changes locally (important)​

./infra.sh sandbox up uses the wizard script and will:

  • regenerate Vagrantfile in the repo root
  • create .vagrant/ (VM state)
  • overwrite deployment/ansible/inventory to point Ansible at the VM

Run it only when you are not simultaneously deploying to a real server, and preferably with a clean git worktree.

Run the sandbox​

./infra.sh sandbox up

Then SSH into the VM:

./infra.sh sandbox ssh

Destroy the VM and cleanup local artifacts:

./infra.sh sandbox down

Notes​

  • The wizard may prompt you for an external admin password if it is not set in your environment.
  • If the sandbox fails, start by re-running ./infra.sh sandbox down and then ./infra.sh sandbox up to ensure a clean VM state.