Getting started Stable

TenkaCloud runs in several modes. Pick the row that matches what you want to do today. Local, Codespaces, and Lite are executable procedures. SaaS is an architecture reference, not a currently supported self-service setup path.

If you already know whether you are developing the platform, organizing an event, participating, or authoring problems, start from the manual for your role.

Conceptual background for modes 4–5 (what each stack is, how tenants provision) lives in deploy modes and launch paths.

1. Local drills — Docker, no AWS

Cloud-independent drill problems run as self-contained Docker containers with a local scoring API. Nothing touches AWS and nothing costs money.

Prerequisites: Bun 1.3.11 and a running Docker daemon (Docker Desktop, or colima on macOS). make doctor diagnoses your setup without installing anything; make local-onboard is the guided installer if you prefer. CPU, memory, Docker allocation and free disk are published as three run profiles with the measurements behind them in docs/local-play-requirements.md; make doctor PROFILE=recommended compares this machine against one of them.

git clone https://github.com/susumutomita/TenkaCloud.git
cd TenkaCloud
make install
git submodule update --init problems   # the drill catalog
make local

make local starts the local scoring API and opens the Participant Portal (port 5175); you pick and start a drill from the portal screen. Useful variants:

make local-list                # list every drill id
make local PROBLEM=<drill-id>  # pre-start one drill
make local-status              # what is running
make local-down                # stop everything

The full local-play manual — the /verify scoring contract, authoring your own container drills — is in docs/local-play.md.

2. GitHub Codespaces — zero install

The same local drills, but the machine is a codespace and setup is automatic (the first build installs Bun, initializes the drill catalog, and starts Docker).

1. Open github.com/codespaces/new for this repo → Create codespace on main.
2. Run the "▷ ローカルプレイ開始" task (Command Palette → Tasks: Run Task, or Cmd/Ctrl+Shift+B) — it runs make local for you.
3. When the Participant Portal is up, open the PORTS tab and click the preview icon next to port 5175.

Two rules keep Codespaces sessions painless:

• Stay inside the codespace. Drill links only work through the port 5175 preview URL; a raw 127.0.0.1 URL pasted into a browser tab on your own machine will not resolve.
• API-style drills are answered from the codespace terminal (e.g. curl http://localhost:<port>/...), because forwarded ports are private to the codespace. The portal shows the drill's endpoints either way.

Codespaces plays cloud-independent drills only — AWS-deployed problems need mode 3, 4, or 5.

3. Lite mode on AWS — console launcher, no local install

Lite mode is the single-organizer platform: Admin Console, Participant Portal, and the problem-deploy backend, deployed as two CloudFormation stacks with a fixed single tenant. This path stands it up entirely from the AWS Console — a launcher stack creates a CodeBuild project that clones the repo and runs the deploy for you.

1. Download infrastructure/templates/lite-pipeline.yaml.
2. Open the CloudFormation Create stack page (the catalog defaults target ap-northeast-1) → Upload a template file → upload it → stack name tenkacloud-lite-launcher.
3. Set TenantAdminEmail (the only required parameter) to the email that should receive the Admin Console invitation.
4. Acknowledge the IAM capability checkbox and create the stack.
5. Open the CodeBuild project from the stack's StartBuildConsoleUrl output and press Start build.

After ~15–30 minutes, the Admin Console and Participant Portal URLs appear in the Outputs of the tenkacloud-lite and tenkacloud-lite-problem-deploy stacks the build created. Sign in with the temporary password mailed to TenantAdminEmail.

Complete teardown: in the same CodeBuild project, use Start build with overrides with ACTION=destroy-all. This also removes the DynamoDB tables and problem-deploy logs owned by the Lite stacks. After it succeeds, delete the tenkacloud-lite-launcher stack itself. Use ACTION=destroy only when you intentionally want to preserve DynamoDB history. If the launcher predates destroy-all, update its CloudFormation stack with the latest template first. Never pass destroy-all to the older buildspec because it treats unknown actions as deploy.

4. Lite mode on AWS — CLI

The same two stacks as mode 3, deployed from your shell — the path you want when you also develop on the platform.

Prerequisites: Bun 1.3.11 and AWS credentials in your shell (profile or SSO) for the target account. cdk bootstrap is not a separate step — the deploy runs it idempotently, and Lambda bundling uses local esbuild (no Docker needed).

git clone https://github.com/susumutomita/TenkaCloud.git
cd TenkaCloud
make install
git submodule update --init problems

# 1. Create the environment file (interactive wizard)…
make env-init
# …or copy the example and fill in AWS_ACCOUNT_ID + TENANT_ADMIN_EMAIL:
#   cp infrastructure/environments/development/.env.example \
#      infrastructure/environments/development/.env

# 2. Deploy (builds the SPAs, bootstraps CDK if needed, deploys both stacks)
make deploy

The command prints the Admin Console and Participant Portal URLs when it finishes. Switch environments with make deploy ENV=production (each environment has its own infrastructure/environments/<env>/.env). Use make destroy-all for complete removal, or make destroy to remove the stacks while preserving DynamoDB history.

Choosing the control-data backend: DynamoDB or Turso

Lite mode stores control data (events, teams, deployments, scores) in one of two backends, selected by CDK_PARAM_CONTROL_DATA_BACKEND in your .env:

These are the only two values — pick the backend per environment before your first real event (the two stores never sync, so a later switch is a data migration, not a flag flip).

The Turso path has unit-test and CDK-synth coverage, but no recorded live run combines a real Turso database, a fresh AWS deployment, and billing behavior. Use DynamoDB for a first production event.

Opting in to Turso is four steps: create a Turso database, store its auth token in SSM as a SecureString, add three lines to your .env (CDK_PARAM_CONTROL_DATA_BACKEND=turso plus CDK_PARAM_TURSO_DATABASE_URL and CDK_PARAM_TURSO_AUTH_TOKEN_PARAMETER_NAME), and make deploy — the first Lambda cold start creates the SQL schema for you, and the deploy gate fails fast if the backend is set while either Turso value is missing. The full walkthrough, the cutover notes for an existing DynamoDB-backed stack, measured monthly costs, and the current live-verification status are in docs/running-costs.md.

5. SaaS mode — multi-tenant

SaaS mode stands up the full multi-tenant platform: the SBT control plane with System Admin invitations, pooled BASIC/ADVANCED tenants, and dedicated PLATINUM silo stacks. Choose it when more than one organization runs events on the same deployment; otherwise Lite mode is the right default.

Current status: make deploy-saas and its supporting code exist, but no recent recorded fresh-AWS run covers setup, tenant creation, problem start, scoring, and teardown. The following is architecture reference, not a production-verified organizer procedure.

Prerequisites: the same toolchain as mode 4, plus SYSTEM_ADMIN_EMAIL and AWS_ACCOUNT_ID in infrastructure/environments/<env>/.env.

make deploy-saas

One command runs all three phases: deploy the control plane + pooled application plane (phase 1), build and host the Admin Console behind CloudFront (phase 2), then re-deploy the control plane with the CloudFront origin wired into Cognito callbacks/CORS (phase 3). The System Admin invitation lands in SYSTEM_ADMIN_EMAIL; from the Admin Console you create tenants, and tenant admins take it from there.

Tear down with make destroy-saas — it is idempotent from any partial state. How tenants provision (pooled vs silo, what the CodePipeline is actually for) is covered in deploy modes and launch paths.

Next steps

• Ship a problem: the first pack tutorial and the problem packs concept.
• Run a competition end to end: run an event.
• Understand the stacks: platform architecture.