Comics MVP: Server, Scrapper and Interface

Quick start

make setup
cp local.env .env
make doctor

# terminal 1 — Go API (comics + auth + scrape)
make go-run

# terminal 2 — Vite frontend
make front-dev

# before pushing
make check

Run make or make help for the full grouped command list. Per-target detail: make help TARGET=go-run.

Make commands

The root Makefile is the canonical developer reference. Common targets:

Area	Targets
Setup	setup, setup-venv, setup-front, setup-go, doctor
Frontend	front-dev, front-dev-https, front-build, front-test, front-deploy
Python	py-test, db-backup, db-restore, db-repair-identity
Go	go-run, go-scrape, go-test, go-import-postgres
Database	db-backup, db-restore, db-check, db-repair-identity, db-audit-covers
Quality	check, check-go, check-front, contract-test, py-test

make check runs Go test/vet/build (including HTTP contract tests), frontend test/build, and Python pytest.

Scrapper and Server deployment (Go primary)

Production and local development default to the Go server on port 8081. It serves comics REST, JWT auth/profile, metrics, and native publisher scrapers. Python remains for DB maintenance scripts and pytest (registration helpers in src/db/scraped_register.py).

Virtual environment (Optional)

make setup-venv
make setup-shell   # prints activation command

Important

For a corrupted virtual env:

make setup-venv-clean
make setup-venv

Installing dependencies

make setup          # Python + Go + frontend + protobuf
make deps-py-upgrade   # bump Python deps and rewrite requirements.txt

Running scraper

make go-scrape      # one pass (CLI)
make go-run         # API + periodic scrape (SCRAPE_INTERVAL default 10m)

Running tests

make py-test
make front-test
make go-test
make check          # all release-path checks

On startup, corrupt SQLite files are rebuilt automatically from src/db/comics.json.

Running Go server

cp go_server/local.env go_server/.env
make go-run

The Go server listens on https://localhost:8081 when tls/comics.crt and tls/comics.key are present. See go_server/README.md for MongoDB, Postgres, and env details.

Import SQLite into Postgres:

make go-import-postgres

Deployment on Heroku

git push heroku
heroku logs --tail

Deployment on Render / Koyeb

Prefer the Go binary or root Docker image:

• Build: docker build -t comics-go-api -f Dockerfile .
• Listen: HTTP_PORT=8081, mount writable src/db → /data/comics.db
• Env: MongoDB (DB_ADDR, DB_USER, DB_PASS), JWT secrets, COMICS_SQLITE_PATH=/data/comics.db
• Optional: SCRAPE_INTERVAL=10m for background publisher sync

Production Docker (SSH workflow)

On merge to main, CI can SSH to the host, git pull, and docker compose up -d --build.

cp go_server/local.env go_server/.env   # set DB_PASS, JWT secrets on the host
make docker-dev                         # local smoke test (API :8081, Mongo :27017)

SQLite lives on the host at src/db/comics.db (mounted into the container at /data). See .github/workflows/ci-cd.yml.

Interface deployment (React + Vite)

Running frontend

Tip

Check the tls folder for HTTPS local development certificates.

make front-dev          # http://localhost:3000
make front-dev-https    # https://localhost:3000 (requires ./tls/comics.crt + .key)

Open the Vite URL printed in the terminal. The page reloads on file changes.

Frontend API env (.env):

• VITE_API_SERVER — preferred API base URL
• VITE_PY_SERVER — legacy fallback for the Python backend

Running tests

make front-test
# or watch mode:
npm run test:watch

Running build and deployment

make front-build
make front-deploy && git push origin   # GitHub Pages

Production build output goes to build/.