Arkie-Library-Frontend/docs/deploy.md

# Deployment

Production frontend deploy is handled by Gitea Actions in `.gitea/workflows/deploy.yml`.

## Trigger

A push to `main` triggers the deploy workflow.

```yaml
on:
  push:
    branches:
      - main
```

## CI/deploy steps

1. Checkout code.
2. Set up Node.js 22 with `actions/setup-node`.
3. Install dependencies with `npm ci`.
4. Type check with `npx tsc --noEmit`.
5. Check formatting with `npm run format:check`.
6. Run tests with `npm test`.
7. Build with `npm run build` using:

   ```bash
   VITE_API_URL=https://api.ark-library.com
   VITE_DISABLE_ADMIN=true
   ```

8. Configure SSH key from `DEPLOY_KEY` secret.
9. `rsync --delete` built `dist/` to both frontend servers:

   ```text
   ec2-user@FRONTEND_1_HOST:/var/www/ark-library/
   ec2-user@FRONTEND_2_HOST:/var/www/ark-library/
   ```

10. Verify both servers have matching `index.html` SHA-256 checksums.
11. Remove temporary SSH key.

## Required repository secrets

The workflow expects these Gitea secrets:

- `DEPLOY_KEY`
- `FRONTEND_1_HOST`
- `FRONTEND_2_HOST`

## Common failures

### Runner disk still shows the old EBS size

If the EC2 runner EBS volume was expanded but CI still reports a small root filesystem (for example `df -h /` still shows 8GB), the partition/filesystem has not grown yet. The deploy workflow runs an early `Ensure runner disk space` step that tries to grow `/` before installing dependencies:

```bash
sudo growpart <root-disk> <root-partition>
sudo resize2fs <root-partition>   # ext filesystems
# or sudo xfs_growfs /           # xfs filesystems
```

If the step cannot find `growpart`, it tries to install `cloud-utils-growpart` with `dnf`/`yum`. If install is blocked, install it manually on the runner host and rerun the workflow. The step also prints `hostname`, `lsblk`, and the visible parent disk byte size. If `growpart` says `NOCHANGE` and the parent disk still shows 8GB, the job is running on the wrong runner/volume or the OS still has not seen the expanded EBS volume; verify the EC2 instance/volume pair and reboot/rescan the runner host.

### Node version is too old

The workflow pins Node.js 22 using `actions/setup-node`. This keeps the self-hosted runner from using an older system Node version during `npm ci`, tests, and build.

If `actions/setup-node` cannot run on the self-hosted runner, upgrade the runner host's Node.js installation to Node 22 or at least Node 20.19 before restarting the runner service.

### TypeScript fails on unused imports

This repo uses `noUnusedLocals` and `noUnusedParameters`. Remove unused imports/variables and rerun:

```bash
npx tsc --noEmit
```

### Format check fails

Run:

```bash
npm run format
npm run format:check
```

Then commit the formatting changes.

### Build uses wrong API

Check `VITE_API_URL` in `.gitea/workflows/deploy.yml` or local `.env`.

### One frontend server differs from the other

The workflow compares remote `index.html` checksums. If it fails, inspect the rsync step and both `FRONTEND_*_HOST` values.