Skip to main content

Blaster setup and development

info

This page covers how to run Blaster on your own machine using local PostgreSQL and Auth.js for authentication.

Blaster game series​

  1. Blaster arcade game
  2. Blaster setup - You are here
  3. Blaster gameplay and features
  4. Blaster architecture
  5. Blaster deployment

1. Prerequisites​

You need:

  • Node.js 18 or later.
  • PostgreSQL 15 or later.
  • A Zitadel OIDC application (or other Auth.js-compatible identity provider).

On macOS, PostgreSQL can be installed and managed via Homebrew.

2. Install dependencies​

From the blaster project root:

npm install

For CI or reproducible installs:

npm run ci:install

This uses npm ci with audit and funding checks disabled to keep logs quiet in CI pipelines.

3. Set up PostgreSQL locally​

Create and initialise the database:

brew install postgresql@15
brew services start postgresql@15

createdb blaster_game
psql blaster_game < database/schema.sql

The legacy database/schema.sql file was used early on. Current deployments use versioned SQL migrations under db/migrations/, but this schema import gets a local dev database running quickly.

Tip: use whoami in a terminal to find your local username when constructing the connection URL.

4. Environment variables​

Create a .env.local file in the project root with, at minimum:

# PostgreSQL Database
DATABASE_URL=postgresql://YOUR_USERNAME@localhost:5432/blaster_game

# Auth.js / Zitadel Authentication
AUTH_SECRET=your_auth_secret
AUTH_ZITADEL_ID=your_zitadel_client_id
AUTH_ZITADEL_SECRET=your_zitadel_client_secret
AUTH_ZITADEL_ISSUER=https://your-zitadel-instance.example.com

Locally, scripts/migrate.ts reads .env.local for connection details. In Kubernetes or other production setups, the environment is injected as POSTGRES_* variables from Secrets and ConfigMaps instead.

5. Running the app locally​

Start the development server:

npm run dev

Then open:

Main commands you will use during development:

npm run dev      # Start development server
npm run build    # Build for production
npm run start    # Start production server
npm run lint     # Run ESLint
npm run migrate  # Run pending database migrations

6. Database migrations​

Blaster uses a custom migration system built on plain pg and versioned SQL files under db/migrations/:

npm run migrate          # Run all pending migrations
npm run migrate:status   # Show migration status

Typical development workflow:

  1. Make a schema change as a new migration file in db/migrations/ (for example 002_add_avatar_url.sql).
  2. Write idempotent SQL using IF NOT EXISTS safeguards.
  3. Run npm run migrate.
  4. Verify with npm run migrate:status.
  5. Test the game and APIs.

The migration logic and pool management live under lib/db/ and are surfaced through scripts/migrate.ts for CLI use.

7. Development ergonomics and testing​

Fast Refresh in Next.js is great for normal UI work but can be annoying during long game sessions. The simple practice is:

  1. Make a code change and save once.
  2. Wait for compilation to finish.
  3. Play a full game without saving again.
  4. Save further changes after the run is complete.

When you need uninterrupted runs, build and start in production mode:

npm run build
npm run start

You can also temporarily disable auto-save in your editor while play-testing.

8. Where to go next​

Once Blaster runs reliably on your machine: