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.

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:

   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:

   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

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.