Skip to content
Planning Game XP

Deploy Your Own

Planning Game is open source. You can deploy your own instance to a Firebase project you control, with full customization over projects, teams, and workflows.

Prerequisites

Section titled “Prerequisites”
  • Node.js 20+ (LTS recommended)
  • npm 9+
  • Firebase CLI: npm install -g firebase-tools
  • Git
  • A Firebase project with these services enabled:
    • Realtime Database
    • Authentication (Email/Password and/or Microsoft provider)
    • Storage
    • Hosting

1. Fork the Repository

Section titled “1. Fork the Repository”
Terminal window
# Fork on GitHub, then clone your fork
git clone git@github.com:YOUR_USER/planning-game-xp.git
cd planning-game-xp
npm install

2. Run the Instance Setup

Section titled “2. Run the Instance Setup”

Planning Game supports multiple deployment instances (e.g., staging and production) from a single codebase. The setup wizard creates the necessary configuration files:

Terminal window
npm run setup

The wizard will ask for:

  • Instance name (e.g., my-team)
  • Firebase project ID
  • Firebase account email (the Google account with access to the project)
  • serviceAccountKey.json path

This creates a directory under planning-game-instances/<name>/ with all instance-specific files.

3. Configure Environment Files

Section titled “3. Configure Environment Files”

Each instance needs environment files for different deployment targets. Create them in the instance directory:

FilePurpose
.env.devLocal development with emulators
.env.prePre-production environment
.env.proProduction environment

Minimum required variables:

Terminal window
# .env.pro example
FIREBASE_API_KEY=your-api-key
FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
FIREBASE_DATABASE_URL=https://your-project-default-rtdb.europe-west1.firebasedatabase.app
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_STORAGE_BUCKET=your-project.firebasestorage.app
FIREBASE_MESSAGING_SENDER_ID=123456789
FIREBASE_APP_ID=1:123456789:web:abcdef

You can find these values in Firebase Console > Project Settings > General > Your apps > Web app config.

4. Build and Deploy

Section titled “4. Build and Deploy”
Terminal window
# Build all instances
npm run build:all


# Deploy all instances
npm run deploy:all

This builds the Astro application, generates the service worker, and deploys to Firebase Hosting.

5. Post-Deploy Setup

Section titled “5. Post-Deploy Setup”

After your first deployment, open the application and complete the initial setup:

Create Your First Project

Section titled “Create Your First Project”
  1. Log in with an admin account
  2. Go to Project Administration
  3. Create a new project with:
    • Project name and abbreviation (used for card IDs like PRJ-TSK-0001)
    • Year
    • Point scale (1-5 linear or Fibonacci)

Add Team Members

Section titled “Add Team Members”

In Project Administration, configure:

  • Developers: Team members who work on tasks. Each gets a dev_XXX ID.
  • Stakeholders: Validators who approve completed work. Each gets a stk_XXX ID.

Set Up Authentication

Section titled “Set Up Authentication”

Configure authentication providers in Firebase Console:

  • Email/Password: Basic authentication
  • Microsoft: For corporate SSO (requires Azure AD app registration)

Connect the MCP Server

Section titled “Connect the MCP Server”

Install the MCP package and run the setup wizard to connect AI agents to your instance:

Terminal window
npm install -g planning-game-mcp
mkdir ~/pg-instances/my-team && cd ~/pg-instances/my-team
cp /path/to/serviceAccountKey.json .
planning-game-mcp init

See the MCP Installation guide for detailed steps.

Firebase Security Rules

Section titled “Firebase Security Rules”

The repository includes security rules for Realtime Database and Storage. Deploy them with:

Terminal window
npm run deploy:rules

Review and customize the rules in database.rules.json and storage.rules before deploying to production.

Cloud Functions

Section titled “Cloud Functions”

Planning Game uses Cloud Functions for:

  • Status transition validation (safety net)
  • AI-generated acceptance criteria
  • Push notifications
  • User provisioning with Custom Claims

Deploy functions separately:

Terminal window
npm run deploy:functions

Updating

Section titled “Updating”

To pull updates from the upstream repository:

Terminal window
git remote add upstream git@github.com:manufosela/planning-game-xp.git
git fetch upstream
git merge upstream/main
npm install
npm run build:all && npm run deploy:all

What’s Next?

Section titled “What’s Next?”