On-Demand Minecraft Server on AWS

Run your own Minecraft server on AWS, control it from a web app, and keep idle cost low by stopping or hibernating when nobody is playing.

This project is web-app first. CLI/API/manual shell flows are supported as optional add-ons.

Quick Setup (Production)

If you want the fastest path from clone to a live panel and server, use the setup script:

git clone <your-repo-url>
cd mc-aws
pnpm setup

pnpm setup runs ./setup.sh, which automatically:

1. Installs/verifies local tools (mise, Node, pnpm, AWS CLI, CDK)
2. Launches the credential wizard (scripts/setup-wizard.sh)
3. Deploys AWS infrastructure with CDK
4. Stores deployment outputs (including INSTANCE_ID) in .env.production and .env.local
5. Deploys the Next.js app to Cloudflare Workers

Accounts/credentials you should have ready

• AWS account (for EC2/Lambda/SSM/SES/CDK)
• Cloudflare zone + DNS API token (for runtime DNS updates)
• Google OAuth client (for web app sign-in)
• GitHub token (repo scope) plus repo/user values (currently required by CDK setup in this repo)

Setup guides:

• AWS Credentials Setup
• Cloudflare Setup
• Google OAuth Setup

Web App Usage (Primary Interface)

Run locally against AWS

cp .env.example .env.local
pnpm dev

Open http://localhost:3000.

Local auth options:

• Google sign-in (when OAuth env vars are configured)
• Dev login route: http://localhost:3000/api/auth/dev-login (pnpm dev enables this by default)

What the panel handles

• Server status, health, and player visibility
• Start, stop, resume, and hibernate operations
• Backup, restore, and backup listing
• Cost views and email allowlist management
• Admin shortcuts for common operational tasks

Role model

• ADMIN_EMAIL: full access
• ALLOWED_EMAILS: can check status and start
• signed-in users not listed above: status-only

Local Development (No AWS Required)

Use mock mode when building UI/API behavior without touching real AWS resources:

pnpm dev:mock
pnpm test:mock
pnpm test:e2e:mock
pnpm mock:scenario running
pnpm mock:reset

More detail:

• Quick Start Mock Mode
• Mock Mode Developer Guide

CLI Addendum (Optional)

The web app is the default workflow. If you want terminal control, these commands call the same API routes:

pnpm server:status
pnpm server:start
pnpm server:stop
pnpm server:resume
pnpm server:hibernate
pnpm server:backup
pnpm server:backups
pnpm server:restore -- <backup-name>

Manual EC2 shell access (advanced):

./bin/connect.sh
./bin/console.sh

API Addendum (Optional)

Primary routes live in app/api:

• GET /api/status
• POST /api/start
• POST /api/stop
• POST /api/resume
• POST /api/hibernate
• POST /api/backup
• POST /api/restore
• GET /api/backups
• GET /api/costs
• GET /api/emails
• PUT /api/emails/allowlist

See API Reference for a broader route map.

Deploying Updates

After initial setup, normal app updates are usually:

wrangler login
pnpm deploy:cf

pnpm deploy:cf uses .env.production by default.

It also writes a temporary .env.production.local during build so next build cannot be overridden by .env.local.

For explicit control:

ENV_FILE=.env.production pnpm deploy:cf

For infrastructure changes:

pnpm cdk:diff
pnpm cdk:deploy

Troubleshooting (Quick)

pnpm setup fails

• Ensure aws sts get-caller-identity works
• Ensure .env.production has required values from the wizard
• Re-run pnpm install then pnpm setup

Google login redirect mismatch

• Add exact callback URLs in Google Console:
  • http://localhost:3000/api/auth/callback
  • https://<your-panel-domain>/api/auth/callback
• Make sure NEXT_PUBLIC_APP_URL matches the deployed panel URL

Cloudflare deployment auth issues

• Use Wrangler OAuth: wrangler login
• Keep DNS runtime token in your deployment env file as CLOUDFLARE_DNS_API_TOKEN
• Avoid exporting CLOUDFLARE_DNS_API_TOKEN globally in your shell

Repo Structure (Quick View)

mc-aws/
├── app/              # Next.js app + API routes
├── components/       # Frontend components
├── hooks/            # Frontend hooks
├── lib/              # Shared AWS/auth/types utilities
├── scripts/          # Setup/deploy/dev helper scripts
├── bin/              # Manual EC2 shell scripts
├── infra/            # AWS CDK stack + Lambda/EC2 assets
├── docs/             # Setup guides and deeper docs
└── tests/            # Vitest + Playwright tests

Key Docs

• AWS Credentials Setup
• Cloudflare Setup
• Google OAuth Setup
• Mock Mode Quick Start
• Mock Mode Developer Guide
• API Reference