Pokémon GO Dex Tracker

Tracks your Pokémon GO Pokédex progress across the full National Dex (#1–1025, Kanto through Paldea): caught, shiny, lucky, Shadow/Purified, and Mega Evolved — per player.

Comes pre-seeded with every species and a fixed player list (Freydis, Romy, Milena) — edit backend/seedData.js before first run if you want to change either. Two extra flags per species are also seeded from there and meant to be updated by hand over time as Niantic adds more content:

• available — whether the species is catchable in GO yet (best-effort snapshot as of mid-2026; species not yet released show up dimmed with a "Noch nicht in GO" badge and their toggles disabled).
• mega_capable — whether the species has a Mega Evolution live in GO (currently 52 species, including the newer additions tied to Legends: Z-A like Falinks and Skarmory).

Local development

Requires Node.js 18+.

# terminal 1 - backend (API on :3000, also serves seed/db)
cd backend
npm install
npm run dev

# terminal 2 - frontend (dev server on :5173, proxies /api to :3000)
cd frontend
npm install
npm run dev

Open http://localhost:5173.

Production build (single process)

cd frontend && npm install && npm run build && cd ..
cd backend && npm install && npm start

Express serves the built React app and the API from the same port (3000 by default, override with PORT).

Deploy with Docker

docker compose up -d --build

This builds the frontend and bundles it with the backend into one image, and connects it to the pkmngodex database on the shared Postgres stack (the pg-shared external network, host pg-shared-db). Set PKMNGODEX_DB_PASSWORD to the role's password (see below). The container always listens on 3000 internally — put it behind your own reverse proxy / firewall rules on the VPS, since there's no login built in.

Changing the host port

If 3000 is already taken on your server, set HOST_PORT to whatever's free instead of editing docker-compose.yml:

cp .env.example .env
# edit .env, e.g. HOST_PORT=3001
docker compose up -d --build

In Portainer, set HOST_PORT and PKMNGODEX_DB_PASSWORD under the stack's Environment variables instead of using a .env file.

API

Method	Path	Description
GET	/api/health	Health check ({"status":"ok","database":"connected"}, 503 if the DB check fails)
GET	/api/version	Git commit hash baked in at build time ({"version":"<hash>"}, "unknown" outside Docker)

Data

• Uses Postgres when DATABASE_URL is set (always true when running via docker-compose.yml) and SQLite otherwise — e.g. running the backend directly for local development. The SQLite file lives at DATA_DIR/pokemon.db (./data/pokemon.db locally).
• Seeding only runs when the pokemon/players tables are empty, so your edits (caught/shiny/lucky/mega/Shadow status) are never overwritten on restart. This also means changes to MEGA_CAPABLE_IDS / UNAVAILABLE_IDS in backend/seedData.js won't apply to an already-seeded database — update the rows directly if you need to backfill those flags later.

CI/CD

.forgejo/workflows/ci.yml runs on every push to main and every PR:

1. backend — installs backend deps (npm ci).
2. frontend — installs frontend deps, lints (oxlint), and builds (npm run build).
3. docker — docker compose build, so a broken image build fails the workflow.
4. deploy — only on pushes to main, after the above pass: POSTs to a webhook (secrets.DEPLOY_WEBHOOK_URL) so Portainer re-pulls this repo and rebuilds/redeploys the stack.

The deploy step needs the webhook URL set as a repo secret first (it's not committed anywhere):

tea actions secrets create --repo freydis/pkmn-go-dex DEPLOY_WEBHOOK_URL "<your webhook url>"

or set it via the web UI: repo → Settings → Actions → Secrets.