Deployment guide

/admin is gated on a role, not on a boolean. Add your Clerk user id to the allowlist:

Find your id in the Clerk dashboard under Users, or sign in and read it from the debug panel at /dashboard. The allowlist takes precedence over the database role column, which means the first owner needs no database row to exist - important, because promoting yourself through the UI would require already being an admin. Comma-separate the value to list several owners.

IAM → Policies → Create policy → JSON, then paste:

1. IAM → Users → Create user - name it octic-platform.
2. Do not enable console access. This identity is for the API only.
3. Attach the policy from step 1.
4. Create access key → Application running outside AWS.
5. Copy the key pair into your environment immediately - the secret is shown exactly once.

Prefer this over long-lived keys when you can:

• On EC2, ECS or Amplify SSR - attach an IAM role to the compute and omit the static keys entirely. The SDK resolves credentials from the instance metadata service automatically.
• Locally - use a named profile from ~/.aws/credentials and set AWS_PROFILE=octic-platform.

The provisioner (lib/aws.ts) resolves the newest Amazon Linux 2023 AMI for the region and CPU architecture (m7i-flex → x86_64, c7g → arm64), then:

• creates a security group named octic-node-<name>, opening the game port on both TCP and UDP, plus 19132/udp for Bedrock cross-play and 22/tcp for SSH. It is idempotent - re-running authorises only the rules that are missing;
• launches the instance with an encrypted gp3 root volume;
• enforces IMDSv2 (HttpTokens: required). IMDSv1 is a well-known SSRF credential-theft vector and there is no reason for a new fleet to permit it;
• tags the instance and volume ManagedBy=octic and Name=<node name>;
• runs a cloud-init script that installs Amazon Corretto 21, creates an unprivileged minecraft user, registers a hardened minecraft.service systemd unit, and applies network sysctls tuned for many concurrent players.

Set these up before you let anyone deploy:

• AWS Budgets - an alarm at 50, 80 and 100% of a monthly figure you are comfortable with. This is the single highest-value safety net.
• Service Quotas - cap Running On-Demand Standard instances to the number of nodes you actually intend to run. A runaway provisioner then hits a quota error rather than your credit card.
• Node.maxServers - the per-node application cap, enforced in the admin UI.
• AWS_EC2_DRY_RUN - leave it on until you have watched a full provision cycle succeed.

Instance pricing used by the admin cost monitor is defined in INSTANCE_TYPES in lib/aws.ts. These are approximate on-demand figures for us-east-1 and drift over time - reconcile against the AWS Pricing API or Cost Explorer before trusting the numbers in a report.

Free-plan accounts cap the plans you can sell

An AWS account still on the Free plan may only launch the instance types AWS marks free-tier eligible, whatever its credit balance - an upgrade, not credits, is what lifts the restriction. The largest eligible type has 8 GB, so every plan above that is unlaunchable on such an account.

Set AWS_EC2_FREE_TIER_ONLY="true" and Octic sizes deployments only from that eligible set (FREE_TIER_INSTANCE_TYPES in lib/aws.ts). A plan too large for the account is then refused at deploy time with plan_exceeds_account and a message naming the limit, rather than being placed on an undersized machine that the kernel would later kill under load. Set the flag back to "false" after upgrading.

Before any of this matters, add the base domains you own: Admin → Domain Pool → Add domain. Each entry has a hostname and a pattern describing how a customer’s chosen label becomes a hostname.

{sub} and {dash} are synonyms - both mean “the label the customer chose in the dashboard”. {server-id} uses the server’s cuid, which is useful for auto-generated hostnames that are never user-editable.

Adding a row here immediately populates the subdomain dropdown in every customer’s Custom Domains tab. There is no deploy step.

Labels are validated against RFC 1123 plus a reserved list (www, api, admin, play, mail, …) in lib/domains.ts. Add per-domain exclusions in the Domain Pool form for names that are only sensitive on one domain.

1. Register or transfer your domain, or add it as a hosted zone: Route 53 → Hosted zones → Create hosted zone.
2. Point your registrar at the four NS records Route 53 gives you.
3. Copy the hosted zone ID - it looks like Z04987621ABCDEFGHIJKL.
4. Attach this policy to your IAM user:

Scoping ChangeResourceRecordSets to a single zone ARN is what stops a bug from editing DNS for your entire account.

1. Add your domain to Cloudflare and move the nameservers at your registrar.
2. My Profile → API Tokens → Create Token → Edit zone DNS template.
3. Scope it to Specific zone → your domain. Do not use a Global API Key - it grants full account access and cannot be scoped or rotated per-service.
4. Copy the token, then find the zone ID on the domain’s overview page.

When a customer connects play.mybrand.com, Octic stores the hostname with type EXTERNAL and a generated challenge token, then displays the two records to create:

It polls DNS for both, and flips the row to VERIFIED once they resolve. The full customer-facing walkthrough is in the DNS setup guide.

The TXT challenge is not redundant. A CNAME alone proves someone can edit DNS; it does not prove they own the domain. Requiring both prevents a third party pointing a hostname they do not control at your infrastructure.

Works without configuration. Modrinth asks that you identify your client:

Responses are cached in-process for five minutes (lib/modrinth.ts) to stay well inside their rate limit.

The CurseForge third-party API requires an approved key. Apply at console.curseforge.com, create the key, and set:

Without a key the CurseForge tab renders an explanatory empty state and the Modrinth tab continues to work - it does not break the add-on browser.

Game-server actions (/api/aws/*) call the EC2 API and can take a few seconds. On the Hobby plan functions are capped at 10 seconds; provisioning usually completes well inside that, but if you see timeouts, move to Pro or set export const maxDuration = 30 in the relevant route handler.

Choose a Vercel region close to your database, not to your users. The functions are thin - they issue a query and an AWS API call, both of which are far more sensitive to distance than the HTML response is.

1. IAM → Roles → Create role → AWS service → Amplify.
2. Name it octic-amplify-ssr.
3. Attach the EC2 policy from the AWS section.
4. Note the ARN.

Amplify → New app → Host web app, connect your repository. Amplify detects Next.js and generates amplify.yml - confirm it includes the Prisma generate step:

1. App settings → Environment variables - add everything from the environment reference.
2. App settings → IAM roles - set the service role to octic-amplify-ssr and leave AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY unset. The SDK picks up the role automatically, which means no long-lived secret exists anywhere in the deployment.

prisma/schema.prisma sets:

• .env is git-ignored. Verify before your first push with git check-ignore -v .env.
• AWS_SECRET_ACCESS_KEY and CLERK_SECRET_KEY are server-only. Never prefix them with NEXT_PUBLIC_ - that inlines the value into the browser bundle.
• Rotate the IAM key every 90 days: IAM → Users → Security credentials → Create access key, deploy the new key, then deactivate the old one and watch for errors before deleting it.

The lifecycle condition in the IAM policy (ec2:ResourceTag/ManagedBy: octic) is the most important control in this document. Do not remove it to “fix” a permission error - if Octic cannot terminate an instance, the instance is almost certainly not one it created, and that is the protection working.

• One node hosts many servers. Node.maxServers is an application-level cap; there is no bin-packing scheduler. Servers are placed on a node when provisioned and do not migrate.
• Metrics are simulated unless you extend getServerMetrics() in lib/servers.ts to query CloudWatch. The function is already async, so the swap needs no call-site changes. Real memory metrics require the CloudWatch agent, which the cloud-init script does not currently install.
• Console output is simulated in demo and seeded modes. Streaming real output needs an agent process on the node - a websocket from the browser to the node’s log file, brokered through the control plane.

Set Ebs.VolumeSize and enable EBS snapshots through Amazon Data Lifecycle Manager. Snapshots are incremental and the only recovery path for a corrupted world; the application does not currently schedule them.