Pokéhunt

Web platform for Pokéhunt: A Trainer's Journey, campus wide event with over 150 participants. Intended for serverless deployment on GCP,but can also be run regularly. Next.js for web and Postgres for database, uses PokeAPI for pokemon sprites and metadata.

Screenshots

soon

Development Setup

npm install

Local PostgreSQL

sudo -u postgres psql
CREATE DATABASE pokehunt;
CREATE USER pokehunt_user WITH ENCRYPTED PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE pokehunt TO pokehunt_user;
\q

Configure Environment

cp .env.example .env.local

Edit .env.local:

PGHOST=localhost
PGPORT=5432
PGUSER=pokehunt_user
PGPASSWORD=your_password
PGDATABASE=pokehunt
DB_CONNECTION_METHOD=direct
DB_USE_SSL=false

QR_SECRET_KEY=mismagius
SECRET_COOKIE_PASSWORD=your-32-char-password-here
NEXT_PUBLIC_ADMIN_PIN=1234
NEXT_PUBLIC_QR_SECRET_KEY=mismagius

NODE_ENV=development

Start Server

npm run dev

Visit http://localhost:3000

Environment Variables

database:

• PGHOST - database host (localhost for local dev)
• PGPORT - port (default: 5432)
• PGUSER - database user
• PGPASSWORD - database password
• PGDATABASE - database name
• DB_CONNECTION_METHOD - direct (local) or connector (GCP)
• DB_USE_SSL - enable SSL (bool)

GCP Cloud SQL:

• INSTANCE_CONNECTION_NAME - GCP instance name
• GOOGLE_APPLICATION_CREDENTIALS - path to service account key

Security:

• QR_SECRET_KEY - server-side QR token secret
• NEXT_PUBLIC_QR_SECRET_KEY - client-side QR secret (must match qr service key)
• SECRET_COOKIE_PASSWORD - cookie encryption key (min 32 chars)
• NEXT_PUBLIC_ADMIN_PIN - admin PIN

App:

• NODE_ENV - Environment (development/production)
• PORT - Server port (optional, default: 3000)

Admin Page

QR Code Generation

const crypto = require('crypto');
const slug = 'dark';
const secret = process.env.QR_SECRET_KEY || 'mismagius';
const token = crypto.createHash('sha256').update(slug + secret).digest('hex');
console.log(`http://localhost:3000/gym?p=${token}`);

Build & Deploy

Local

npm run build
npm run start

GCP Cloud Run

Environment variables:

DB_CONNECTION_METHOD=connector
INSTANCE_CONNECTION_NAME=project:region:instance
PGUSER=postgres
PGPASSWORD=your-password
PGDATABASE=pokehunt
DB_USE_SSL=true
QR_SECRET_KEY=your-secret
SECRET_COOKIE_PASSWORD=your-password
NEXT_PUBLIC_ADMIN_PIN=your-pin
NEXT_PUBLIC_QR_SECRET_KEY=your-secret
NODE_ENV=production

Attach Cloud SQL instance and configure VPC connector in Cloud Run settings.