# Deploying

Every instance runs on SRVMPHTAT2MEC, from its own checkout, compose project and database:

| instance | checkout | compose file | project | URL |
| --- | --- | --- | --- | --- |
| `prod` | `/var/www/html` | `docker-compose.yml` | `html` | https://axioma-study.kz |
| `nomad` | `/var/www/nomad` | `docker-compose.branded.yml` | `axioma-nomad` | https://nomad.axicrm.com |
| `demo` | `/var/www/demo` | `docker-compose.demo.yml` | `axioma-demo` | https://demo.axioma-study.kz |

A deploy is [`scripts/deploy.sh <instance>`](scripts/deploy.sh). It runs these steps and stops
at the first failure:

1. Refuses if tracked files are edited locally. The one exception is a branded instance's own
   `images/logo.png` / `images/favicon/*`, which it sets aside and puts back afterwards.
2. Backs the database up with `backup_db.sh`.
3. Fast-forwards to `origin/main`.
4. Runs `composer install` if `composer.lock` changed.
5. Rebuilds the image if the `Dockerfile` or `docker/php/` changed, or when `--rebuild` is passed.
6. Runs `artisan db:migrate`.
7. Clears caches.
8. Checks that `/login.php` answers 200.

The table above lives in the script. Add a new instance there.

## From GitLab (the normal way)

Every green pipeline on `main` shows three manual jobs: `deploy:prod`, `deploy:nomad` and
`deploy:demo`. Click one to deploy that instance. To force an image rebuild,
run the job with the variable `DEPLOY_ARGS` = `--rebuild`.

The CI key runs whichever `deploy.sh` is in `/var/www/html`. Deploy **prod first**, so its copy
of the script is current before you deploy the other instances.

### One-time setup (you do this, nobody else handles the key)

1. On SRVMPHTAT2MEC, as root, create a key used only for this:
   ```bash
   ssh-keygen -t ed25519 -N '' -C gitlab-deploy -f /root/gitlab-deploy
   ```
2. Pin it to the deploy script. Add one line to `/root/.ssh/authorized_keys`: the contents of
   `/root/gitlab-deploy.pub`, prefixed like this:
   ```
   restrict,command="/var/www/html/scripts/deploy.sh" ssh-ed25519 AAAA... gitlab-deploy
   ```
   `command=` means this key can run nothing but `deploy.sh`. The script reads the instance name
   from `$SSH_ORIGINAL_COMMAND` and rejects anything that isn't an instance name or `--rebuild`.
   `restrict` turns off port forwarding, a TTY and agent forwarding.
3. In GitLab, go to **Settings → CI/CD → Variables** and add three variables, all **Protected**
   so only `main` can read them:
   - `SSH_PRIVATE_KEY`: type **File**, value is the contents of `/root/gitlab-deploy`.
   - `SSH_KNOWN_HOSTS`: the output of `ssh-keyscan <server address>`, run from a machine you
     trust.
   - `DEPLOY_HOST`: the server's address. Also set `DEPLOY_USER` if it isn't `root`.
4. Delete `/root/gitlab-deploy` (the private half) from the server once it's in GitLab.
5. Check that `main` is a protected branch, so the Protected variables are only exposed there.

## By hand

```bash
ssh root@<server> /var/www/html/scripts/deploy.sh nomad
```

## Database migrations

Schema changes are `docker/mysql/init/NNN_name.sql` files, applied by `php artisan db:migrate`,
which records each one in `schema_migrations`. See [CLAUDE.md](CLAUDE.md#database).

**Before an instance's first deploy with this,** it has to be baselined. Every existing
instance's schema was built by hand, so `schema_migrations` doesn't exist there yet, and
`db:migrate` refuses to run until it does. Do this once per instance:

```bash
cd /var/www/<checkout> && git pull --ff-only     # gets the new commands
docker compose -f <compose file> -p <project> exec -T \
  -e DB_USER=root -e DB_PASS="$(grep -E '^MYSQL_ROOT_PASSWORD=' .env | cut -d= -f2-)" \
  app php /var/www/html/laravel/artisan db:schema-diff
```

`db:schema-diff` builds what the files describe into a scratch `<db>_schemaref` database, then
compares it with the instance and drops it again. For each migration it reports one of:

- **looks applied**
- **looks NOT applied**
- **partial**: resolve these by hand
- **no visible schema change**: data-only files, which you have to check by hand

It ends with a suggested `db:migrate --mark-applied=...` command. Check the lists, run that
command, then `db:migrate --status`, then deploy normally. The deploy applies whatever is still
pending.
