Competition organizer manual Preview

This manual is for someone who prepares TenkaCloud in their own AWS account and runs an event. Its executable instructions cover Lite mode, the path that can currently be offered to organizers. SaaS is kept separate in SaaS operating status.

What this manual helps you do

• Decide whether your use case calls for Lite or SaaS.
• Prepare TenkaCloud with the Lite deployment pipeline.
• Confirm the Application Admin Console and Participant Portal.
• Rehearse problem start, scoring, reset, and stop with a test team.
• Find the input contract and exact error guidance before changing a setting.

Choose Lite or SaaS by use case

Choose Lite when in doubt. Even when a use case belongs to SaaS, do not use the SaaS path for a live event unless your team has verified it in a real environment and can operate incident recovery.

The Lite deployment pipeline

“Deployment pipeline” here means a CloudFormation template that creates one CodeBuild project. CodeBuild then fetches the source, installs the required software, runs make deploy, and prints the access URLs in sequence. It does not use the AWS product named CodePipeline.

The source is infrastructure/templates/lite-pipeline.yaml.

Deploy from the AWS console (recommended)

1. Open Getting started: Lite console launcher.
2. Sign in to AWS and enter TenantAdminEmail in CloudFormation.
3. Read the IAM acknowledgement and create the stack.
4. Open the CodeBuild link in the stack output and press Start build.
5. Wait for the build status to become Succeeded.
6. Copy the Application Admin Console and Participant Portal URLs from the end of the log.
7. Use the invitation sent to TenantAdminEmail for the first sign-in.

If the build fails, find the first ERROR in the CodeBuild log. Do not delete the launcher first. Look up the same text in the Lite settings message reference.

Deploy from a local checkout

Use this path only when you can operate the repository:

make env-init ENV=development
make deploy ENV=development

make env-init asks for required values and creates infrastructure/environments/development/.env. Editing .env does not update a running environment; run make deploy after reviewing the change.

The Lite event flow

1. Sign in to the Application Admin Console as the organizer.
2. Activate the problem pack you will use.
3. Create the event, teams, and problem selection.
4. Register a test competitor AWS account.
5. Start a problem for the test team and open its endpoint.
6. Submit a real TC{...} value and confirm the score changes.
7. Reset the problem and confirm a new environment can start.
8. Stop the problem and confirm its stack is gone from the competitor account.
9. Give participants only the Participant Portal URL, team key, start time, and participant manual.

For screen-level details, see Run an event end to end.

Choose where control data is stored

Control data means events, teams, problem state, endpoints, scores, organizer accounts, and audit records. It is separate from a participant's problem environment.

The Turso path is covered by unit tests and CDK synth, but it has not been live-verified as a complete real-Turso, fresh-AWS, and billing flow. Use dynamodb for the first real event.

Changing the backend later does not migrate data. DynamoDB and Turso do not synchronize, and retained DynamoDB tables can continue to incur cost.

Change settings

A first-time Lite setup asks for three values:

The Lite setting reference lists the purpose, format, default, character or numeric limits, example, and invalid input behavior for the remaining settings. The Lite settings message reference lists each emitted message with its cause and operator action.

Scoring and cost warning email

When CDK_PARAM_OPS_ALERT_EMAIL is set, AWS sends a subscription confirmation email. After confirmation, email is sent for exactly these three conditions:

1. The scoring function records at least one error in five minutes.
2. The scoring function has no invocation for five consecutive minutes.
3. Actual monthly AWS spend exceeds CDK_PARAM_OPS_MONTHLY_COST_LIMIT_USD.

This does not notify every failure in problem start, stop, or cleanup. When the email setting is absent, these three warnings are not sent.

Organizer MCP

The organizer MCP endpoint belongs to the Always-On control plane. It is not automatically added by the Lite deployment pipeline described on this page. The Application Admin Console remains the normal operating surface for a Lite event.

An operator validating Always-On mode can connect to {ALWAYS_ON_CONTROL_PLANE_ORIGIN}/mcp/organizer and provide an organizer Auth0 access token as Authorization: Bearer .... Store that token in the client's secret facility; never paste it into a configuration file, prompt, Issue, or log.

Before authentication, the client follows the resource_metadata link in the 401 Unauthorized response's WWW-Authenticate header. The current setup requires an OAuth client registered with Auth0 in advance. TenkaCloud does not provide a DCR endpoint. Use CIMD only when the configured authorization server explicitly advertises support.

The only current tool is list_events. It returns events belonging to the authenticated tenant and cannot create, change, deploy, stop, or delete anything. It also omits other tenants' events, team keys, flags, and scoring secrets. The MCP client must support revision 2026-07-28, call server/discover, and send the per-request protocol headers and _meta envelope. The MCP host must show the tool name and arguments and obtain the organizer's approval before every call. Do not use a client that skips that confirmation.

Before participants arrive

• A test team used the same permissions and Region as participants.
• Every endpoint opened from the expected network.
• A real flag changed the score.
• Reset created a fresh problem environment.
• Stop removed the problem stack from the competitor account.
• The event time, team-key delivery, and support contact are decided.
• AWS administrator credentials, .env, and database tokens are not shared.

Teardown

Remove Lite first and the launcher CloudFormation stack last:

make destroy-all ENV=development

For a console deployment, run the launcher's CodeBuild project with ACTION=destroy-all. Deleting the launcher first removes the same automation path used to clean up Lite.

SaaS operating status

The repository contains make deploy-saas, the SBT control plane, tenant provisioning code, and the tenkacloud-saas-pipeline that updates existing tenants. However, there is no recent recorded run that takes a fresh AWS environment through setup, tenant creation, problem start, scoring, and teardown.

This manual therefore does not present SaaS commands as an alternative Lite procedure. Use Deploy modes and launch paths only as an architecture reference, then verify the full flow in a dedicated environment before evaluating SaaS.