Deployment

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

Trigger

A push to main triggers the deploy workflow.

on:
  push:
    branches:
      - main

CI/deploy steps

Checkout code.
Set up Node.js 22 with actions/setup-node.
Install dependencies with npm ci.
Type check with npx tsc --noEmit.
Check formatting with npm run format:check.
Run tests with npm test.

Build with npm run build using:

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

Configure SSH key from DEPLOY_KEY secret.

rsync --delete built dist/ to both frontend servers:

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

Verify both servers have matching index.html SHA-256 checksums.
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:

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:

npx tsc --noEmit

Format check fails

Run:

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.

2.9 KiB Raw Blame History