# Deploying the fleet API by release folders

Every deploy builds a new folder from one commit; the live path is a link switched to it. No git on the box, nothing
merged into the code that serves, and the way back is the same link switched back.

## Layout on a box
- `$BASE/releases/<sha>/`: one folder per commit (`$BASE` = `/var/www/html/fleet` in prod).
- `$BASE/shared/.env`: the only `.env` (mode 640, owner dadycar_backend, group www-data). Every release links to it:
  edit that file (or `sed -i --follow-symlinks` through the link), never a copy inside a release.
- Every release links `storage` → `$STORAGE` (`/var/www/html/storage`) and `public/storage` → `$STORAGE/app/public`:
  uploads, logs, cache and the scheduler's locks are shared by all releases.
- `$APP` (`/var/www/html/app`): a link to the live release. Apache, the cron, supervisor, reverb and the scripts keep
  using that path.
- `$BASE/deploys.log`: one line per deploy; `<release>/.release`: what it is and who deployed it.

## Deploy (on the PC, Git Bash)
```
bash deploy/deploy-from-pc.sh prod                 # origin/develop's tip
bash deploy/deploy-from-pc.sh prod <commit>        # a given commit, pushed
bash deploy/deploy-from-pc.sh uat                  # the rehearsal target
```
1. The commit must be on GitHub; the live release must be its ancestor. The merges in between and the files that need
   care (migrations, composer.lock, config, routes, .env.example) are listed, then the script asks `yes`.
2. `git archive` of the commit, sha256, upload; `deploy/release.sh` runs on the box with `deploy/targets/<target>.sh`.
3. On the box: unpack, links, `vendor` copied from the live release when composer.lock did not change, then
   `composer install --no-dev`; the new folder must boot and list its routes.
4. Pending migrations: a full dump first (prod), maintenance mode, `migrate --force` from the new folder, then the
   switch. A pending migration whose file holds the word `ONE_WAY` (it drops or renames what the live code reads)
   stops the deploy before anything changes: run it by hand, with a plan.
5. Switch the link, reload php8.2-fpm, `queue:restart`, restart reverb; probes. A probe that does not answer as
   expected puts the previous release back. The last line printed is the way back by hand.
6. Five releases kept; `legacy-*` folders are never removed by the script.

Output copy on the PC: `~/server-runs/fleet-deploy-<target>-<date>.txt`.

## Once per box: the cutover
`bash deploy/deploy-from-pc.sh <target> <commit the box runs> --cutover`: the old git tree must hold that commit's code
(storage aside); its `.env` is copied to `shared/`; the tree becomes `releases/legacy-<date>` and `$APP` the link. The
way back links `$APP` to that legacy folder. After it, `git pull` in `$APP` no longer exists: deploys go through this
script only.

## Rules that stay
- Never `config:cache`, never `config:clear` (the script stops if `bootstrap/cache/config.php` exists).
- No route cache either.

## Test
`bash deploy/test/stub-run.sh` on Linux (WSL): release.sh on a fake box with stubbed commands (cutover, deploy, failed
probe and rollback, ONE_WAY, wrong sum, migration, prune).
