Deployment

Overview

The playcademy deploy command handles the complete deployment workflow using one command.

The Deployment Process

Quick Start

$ playcademy deploy

$ playcademy deploy --env production

Prerequisites

bun run build # or whatever your build command is

npm run build # or whatever your build command is

pnpm run build # or whatever your build command is

yarn run build # or whatever your build command is

Specifying Build Path

You can specify the build path in three ways:

export default {
    name: 'My Project',
    buildPath: '.playcademy/my-project.zip',
}

$ playcademy deploy --build ./dist/my-project.zip

$ playcademy deploy

Current Configuration:  Name:   My Project  Status: Not deployed? Path to project zip file: .playcademy/my-project.zip

Backend Deployment

Backend Deployment Behavior

Deployment behavior is determined by the following factors:

Examples:

$ playcademy deploy  # Deploy normally (backend changes included if changes detected)$ playcademy deploy --force-backend  # Force backend deployment (when no changes detected)$ playcademy deploy --no-backend  # Skip backend (only deploy frontend changes)

Backend URLs

After deployment, your backend is available at:

Environments

Staging vs Production

The CLI supports two deployment environments:

Deploy to staging:

$ playcademy deploy  # Staging is default

Deploy to production:

$ playcademy deploy --env production

Why Staging First?

Staging allows you to:

1. Test: Verify project works in production-like environment
2. Debug: Check backend routes and integrations
3. Preview: Share with teammates before going live
4. Iterate: Make changes without affecting live users

Change Detection

The CLI intelligently detects what changed and only deploys what's necessary.

What Gets Checked

Deployment Scenarios

No changes detected:

✔ No changes detected in playcademy.config.js
✔ No changes detected in frontend zip file
✔ No changes detected in API routes

✦ Nothing to do

Frontend changed:

Changes detected:

  Frontend
    Build: 85.23 KB → 86.12 KB  (↑ 0.89 KB)

✔ Update My Project to a new version? Yes

Backend changed:

Changes detected:

  Backend
    Custom Routes: 42.34 KB → 45.12 KB  (↑ 2.78 KB)

✔ Update My Project to a new version? Yes

Database Migrations

When your project uses a database integration, playcademy deploy automatically detects schema changes and applies migrations to your remote database.

Schema Strategies

The CLI supports two strategies that match how you work with Drizzle locally:

The strategy is auto-detected based on whether migration files exist (db/migrations/meta/_journal.json), or can be set explicitly:

export default {
    name: 'My Project',
    integrations: {
        database: {
            strategy: 'migrate', // or 'push'
        },
    },
}

Previewing Schema Changes

Use playcademy db diff before deploying to preview the SQL that will be applied:

$ playcademy db diff   # Preview migration SQL$ playcademy deploy    # Deploy with auto-migration

Already using push-mode and want to switch? See Switching from Push to Migrate.

Interactive Prompts

If required information is missing, the CLI prompts you:

$ playcademy deploy

Current Configuration:  Name:   My Project  Status: Not deployed? Path to project zip file: ./dist/project.zip? Deploy this project? Yes

Skipping Prompts

Provide all information via config or flags for non-interactive deployments:

$ playcademy deploy \  --name "My Project" \  --build ./dist/project.zip \  --env staging

Dry Run

Preview what would be deployed without making changes:

$ playcademy deploy --dry-run

Sample output:

Deployment Plan (Dry Run)

  Action:          Create new project
  Deploy Frontend: true
  Deploy Backend:  true
  Build Size:      86.06 KB
  Backend URL:     https://my-project-staging.playcademy.gg/api
  Custom Routes:   2
  Integrations:    Timeback

✦ Dry run complete

Command Options

Full deployment command reference:

$ playcademy deploy [options]

See Commands Reference for complete details.

Secrets Integration

Secrets from your .env file are automatically included in the deployment flow. When you have pending secret changes, they appear alongside other changes in the diff:

Changes detected:

  Frontend
    Build: 85.23 KB → 86.12 KB  (↑ 0.89 KB)

  Secrets
    Added: API_KEY
    Updated: DATABASE_URL

? Update My Project to a new version? Yes

✔ Uploading frontend
✔ Pushing 2 secrets
✔ MyGame updated successfully!

Required Secrets

If your project uses integrations that require secrets (like authentication), the CLI validates these before deployment:

┌─ MISSING SECRET: BETTER_AUTH_SECRET
│ The auth integration requires BETTER_AUTH_SECRET to be set in .env
│
│ Learn more: https://docs.playcademy.net/platform/integrations/authentication
└─

Add the missing secret to your .env file and redeploy.

Updating Your Project

Made changes? Redeploy anytime:

$ bun run build$ playcademy deploy

Observability

Streaming Logs

After deploying, stream real-time logs from your application:

$ playcademy logs # or cd my-project && playcademy logs

✔ Connected to staging logs for "my-project"  Press ctrl+c to stop10:39:51 AM GET /api/hello 200 OK10:39:52 AM POST /api/validate-answer 200 OK

See playcademy logs for more information.

What's Next?