Files

T

anthonyandClaude Sonnet 5 3c0de7e742 docs: fill migration-workflow gaps found in final review

CLAUDE.md:
- Add the one-time `prisma migrate resolve --applied 0_init` baseline
  step that must run before the first `migrate deploy` against any
  environment (o2switch production included) whose conversion_jobs
  table predates Prisma. Without it, migrate deploy tries to
  CREATE TABLE against a table that already exists and fails, leaving
  migration history stuck.
- Document the actual, tested result of `prisma migrate dev` against
  the local dev DB: it fails with P3014 because convert_user lacks
  CREATE DATABASE/DROP DATABASE privileges needed for the shadow
  database. Document the verified fallback (`migrate diff
  --from-migrations ... --to-schema-datamodel ...` + manual migration
  folder + `migrate resolve --applied`) as the supported way to create
  new migrations here.

README.md:
- Local development step 2 referenced the deleted db/schema.sql;
  replaced with the real `prisma migrate deploy` invocation, which
  creates conversion_jobs fresh on an empty local database. Reordered
  so `npm install` runs first, since the migrate command needs
  node_modules/@prisma/client.
- Deployment on o2switch: added the same one-time baseline step
  (clearly marked, not to be repeated) before the first migrate
  deploy on that server, and added `prisma migrate deploy` to the
  "every subsequent deployment" checklist, after npm install and
  before restarting the app.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-07-31 01:54:23 +02:00

3.0 KiB

Raw Blame History

File Converter

Local development

Copy .env.example to .env and fill in your local MariaDB credentials.
Install dependencies: npm install
Export those same DB_HOST/DB_USER/DB_PASSWORD/DB_NAME values from .env into your shell, then apply the schema with Prisma Migrate (creates the conversion_jobs table fresh, since a new local database starts empty): DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate deploy
Run the API: npm start
Run the worker (separate terminal): npm run worker
Run tests: npm test (requires the same MariaDB reachable via your .env vars, exported into the shell)

Deployment on o2switch

Upload the project (excluding node_modules/) via SSH/Git.
Create/adjust .env on the server with production values (STORAGE_DIR pointing to a writable path under your account, MariaDB credentials from cPanel).
npm install --include=dev (never with --ignore-scripts — Puppeteer needs its postinstall step to download Chromium).
Configure the app in cPanel "Setup Node.js App", pointing its entry point at src/server.js. Passenger manages this process (start/stop/restart).
Start the worker independently of Passenger, over SSH: ./node_modules/.bin/pm2 start ecosystem.config.cjs, then pm2 save. Try pm2 startup to survive a server reboot; if that's not permitted without root on this account, fall back to a cPanel cron job every 5 minutes that runs pm2 resurrect (or checks pm2 list and restarts the app if absent) — validate which option this hosting plan actually allows once connected over SSH.
Add a cPanel cron job to run the cleanup script periodically, e.g. every 15 minutes: */15 * * * * cd /home/gaan6043/convert.ombrora.com-node && /home/gaan6043/nodevenv/convert.ombrora.com-node/24/bin/node src/cleanup.js > /dev/null (adjust the path and node binary location to match your actual account — check with which node over SSH).
ONE-TIME, before ever running prisma migrate deploy on this server: the o2switch database already has the conversion_jobs table (created by hand, before this project used Prisma), but no _prisma_migrations tracking table. Running migrate deploy first would try to CREATE TABLE conversion_jobs again and fail with a "table already exists" MySQL error, leaving Prisma's migration history stuck and needing manual recovery. Avoid that by baselining the existing table once, ever, on this server, before step 8's migrate deploy runs for the first time: DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate resolve --applied 0_init Do not repeat this step on later deployments — after this one-time run, migrate deploy (step 8) is the correct command going forward.
On every subsequent deployment: pull changes, npm install, apply any pending migrations with DATABASE_URL=$(node scripts/printDatabaseUrl.js) npx prisma migrate deploy, npm run build (frontend), then restart the Passenger app from cPanel and pm2 restart convert-worker.

3.0 KiB Raw Blame History

File Converter

Local development

Deployment on o2switch

3.0 KiB

Raw Blame History