Hosted Early-Dev Runbook

This is the operator runbook for bringing up the first low-cost EchoSpire tester environment.

Use this runbook when the goal is not infrastructure experimentation, but a working hosted environment that external testers can reach.

This runbook assumes the repository already contains the hosted deployment assets, including the root render.yaml Blueprint.

Outcome

When this runbook is complete, you should have:

• a public docs site on Cloudflare Pages
• a public Admin site on Render
• a public API on Render
• PostgreSQL hosted on Neon
• Redis hosted on Upstash
• JSON fallback telemetry enabled in the API container

Preflight

Before starting, confirm the following:

1. The latest deployment commit is pushed to the repository default branch.
2. You have logins for Render, Neon, Upstash, and Cloudflare.
3. You have authority to connect the repository to those providers.
4. You have one AI API key available if you want AI-generated hero names on day one.

If you do not have an AI API key yet, continue anyway. The API will fall back to non-AI hero naming.

Step 1: Create PostgreSQL In Neon

1. Sign in to Neon.
2. Create a new project.
3. Choose a project name like echospire-early-dev.
4. Keep the default Postgres version unless you have a reason to pin another one.
5. After the project is created, open the dashboard and locate the connection details.
6. Copy the PostgreSQL connection string.

Store this value for the Render API service as:

• ConnectionStrings__Postgres

Use the raw Neon connection string value only.

Do not prefix it with a variable name.

Checkpoint:

• you have one valid Neon connection string copied and ready

Step 2: Create Redis In Upstash

1. Sign in to Upstash.
2. Create a new Redis database.
3. Name it something like echospire-early-dev.
4. Use the default region unless you have a latency reason to match Render more closely.
5. Open the database details page.
6. Copy the Redis connection string.

Store this value for the Render API service as:

• ConnectionStrings__Redis

Use the raw Upstash Redis URL only.

Do not paste REDIS_URL= or surrounding quotes into the Render value.

Checkpoint:

• you have one valid Upstash Redis connection string copied and ready

Step 3: Deploy API And Admin In Render

1. Sign in to Render.
2. Choose New.
3. Choose Blueprint.
4. Connect the GitHub repository if it is not already connected.
5. Select this repository.
6. Render should detect the root render.yaml file automatically.
7. Continue with Blueprint import.

You should see two services:

• echospire-api
• echospire-admin

Render Values To Enter

For echospire-api, provide these values when prompted:

• ConnectionStrings__Postgres: paste the raw Neon connection string
• ConnectionStrings__Redis: paste the raw Upstash Redis URL
• AiCompletion__ApiKey: paste an AI key if you want AI naming enabled

Leave these Blueprint defaults as they are unless you have a deliberate reason to change them:

• ASPNETCORE_ENVIRONMENT=Production
• Jwt__Issuer=EchoSpire
• Jwt__Audience=EchoSpire.Clients
• Telemetry__Kusto__ClusterUri= blank
• Telemetry__Kusto__Database=EchoSpire
• Telemetry__JsonFallbackPath=/tmp/echospire-api-telemetry.ndjson
• Hosting__DisableHttpsRedirection=true
• AiCompletion__Provider=OpenAI
• AiCompletion__Endpoint=https://api.openai.com/v1/chat/completions
• AiCompletion__Model=gpt-4o-mini

For echospire-admin, set ApiBaseUrl to the public Render API URL:

• https://echospire-api.onrender.com

If you later move the API behind a custom domain, update ApiBaseUrl to that public HTTPS URL.

Render Deployment Checks

1. Start the Blueprint deployment.
2. Wait for echospire-api to finish building and become healthy.
3. Wait for echospire-admin to finish building and become healthy.
4. Open the API public URL and verify the health endpoint returns success.
5. Open the Admin public URL and verify the site loads.

Primary health URL:

• /api/v1/health
• /api/v1/health/db

Checkpoint:

• Render shows both services as live
• the API health endpoint responds successfully
• the Admin UI loads in a browser

Step 4: Publish Docs On Cloudflare Pages

1. Sign in to Cloudflare.
2. Open Workers & Pages.
3. Choose Create application.
4. Choose Pages.
5. Connect the GitHub repository if needed.
6. Select this repository.

7. Use these build settings:

8. Framework preset: None

9. Build command: pip install -r requirements-docs.txt && mkdocs build --clean
10. Build output directory: site

11. Root directory: repository root

12. Start the deployment.

13. Wait for the Pages build to complete.
14. Open the generated Pages URL.

Checkpoint:

• the docs home page loads
• the official docs index loads
• the hosted deployment docs are visible in navigation

Step 5: Smoke Test The Environment

Run this smoke test after all three surfaces are live.

Docs

1. Open the docs site.
2. Navigate to the official docs index.
3. Open the hosted deployment guide.
4. Open this runbook page.

API

1. Open the API health endpoint.
2. Open the database health endpoint.
3. Confirm both responses are successful.
4. Confirm the database health response includes nonzero factions and classes counts after seeding.
5. If Swagger is enabled in the deployed environment, verify it loads.

Admin

1. Open the Admin site.
2. Confirm the first page renders without a server error.
3. Navigate to one or two API-backed screens.
4. Confirm those screens do not fail because of API connectivity.

Persistence And Cache

1. Exercise one API path that hits the database.
2. Exercise one Admin action that results in an API call.
3. Watch Render logs for connection or auth errors.

Recommended DB verification URL:

• /api/v1/health/db

If the API is failing on startup, the first things to check are:

• invalid Neon connection string
• invalid Upstash connection string
• malformed JWT secret or missing generated secret
• accidental override of ApiBaseUrl in Admin

Step 6: Optional Custom Domains

Only do this after the default provider URLs are working.

Recommended final hostnames:

• docs.<your-domain> for Cloudflare Pages
• admin.<your-domain> for Render Admin
• api.<your-domain> for Render API

Provider actions:

1. Add the custom domain in the provider dashboard.
2. Copy the DNS records the provider asks for.
3. Create the DNS records in your DNS host.
4. Wait for provider verification and TLS issuance.
5. Re-run the smoke test on the custom domains.

Step 7: Release Flow After First Bring-Up

Once the hosted environment exists, the ongoing release loop is simple:

1. Push changes to the branch used by the connected providers.
2. Render auto-deploys the API and Admin changes.
3. Cloudflare Pages rebuilds the docs site.
4. Re-run the smoke test after each significant deploy.

If you want stricter release control later, switch Render services from auto-deploy to manual deploy and treat the provider dashboards as the release gate.

Step 8: Build And Distribute The Console EXE

Use the Build ConsoleGame Client GitHub Actions workflow to produce a downloadable Windows client that points at the hosted API.

Workflow location:

• .github/workflows/consolegame-client-release.yml

How to run it:

1. Open GitHub Actions.
2. Run Build ConsoleGame Client manually.
3. Leave the default api_base_url as https://echospire-api.onrender.com unless the API moved to a custom domain.
4. Set artifact_name to something release-shaped, such as tester-drop-001.
5. Wait for the workflow to finish.
6. Download the uploaded artifact ZIP from the workflow run.

What the ZIP contains:

• EchoSpire.ConsoleGame.exe
• appsettings.json
• README.txt

Distribution rule:

• send the ZIP as-is to testers
• do not send only the EXE by itself
• keep appsettings.json next to the EXE

Why this works:

• the packaged appsettings.json is stamped with the hosted API URL
• the client already authenticates against the live API at startup
• testers do not need a local API running

Manual override for support cases:

• set ECHOSPIRE_Api__BaseUrl to another API URL if you need to retarget the client without editing files

Tester verification steps:

1. Unzip the package.
2. Launch EchoSpire.ConsoleGame.exe.
3. Confirm the console shows Connecting to API at https://echospire-api.onrender.com...
4. Confirm the console then shows Authenticated.
5. If it fails, check internet access and confirm the API health endpoint still works.

Rollback

If a bad deploy lands:

Render

1. Open the affected service.
2. Open the deploy history.
3. Redeploy the last known good deploy.

Cloudflare Pages

1. Open the project.
2. Open deployment history.
3. Promote or redeploy the last known good build.

Data Services

Do not change Neon or Upstash during an application rollback unless the failure is clearly caused by a credentials or schema issue.

Troubleshooting

API unhealthy on Render

Check these first:

• ConnectionStrings__Postgres
• ConnectionStrings__Redis
• Render service logs
• whether the container is binding to the expected port
• whether the service is running the image entrypoint instead of an overridden dockerCommand

Admin loads but API-backed screens fail

Check these first:

• whether echospire-api is healthy
• whether Render kept the ApiBaseUrl service reference intact
• whether the API auth/login endpoint is reachable from Admin

Docs build fails on Cloudflare Pages

Check these first:

• the build command matches pip install -r requirements-docs.txt && mkdocs build --clean
• the output directory is exactly site
• the root directory is the repository root

AI naming does not work

Check these first:

• AiCompletion__ApiKey
• AiCompletion__Endpoint
• AiCompletion__Model

If those remain unset, the system should continue to function with fallback hero naming.

Definition Of Done

This rollout is done when all of the following are true:

• docs are public and readable
• API health is green
• Admin is reachable and can talk to the API
• Postgres and Redis connectivity are stable
• the environment can survive a normal code redeploy