Skip to content

Hosted Early-Dev Deployment

This document defines the recommended low-cost hosting path for EchoSpire during early external testing.

It exists because the full pseudo-production VM stack is heavier than what is needed for the first tester cohort, especially when the goal is to keep costs near zero for as long as possible.

For the operator procedure, use Hosted Early-Dev Runbook.

Recommendation

Use the following split-platform model:

  • Cloudflare Pages for docs hosting
  • Render for the API and Admin web applications
  • Neon for PostgreSQL
  • Upstash for Redis
  • JSON fallback telemetry instead of Kusto during the early hosted phase

This is the most practical compromise between cost, setup complexity, and operational usefulness.

Why This Version Wins Early

This hosted path is better than a full VM stack for the current stage because it:

  • minimizes infrastructure setup work
  • avoids paying for an always-on Linux VM too early
  • keeps the public surfaces online for testers
  • preserves a later migration path to a fuller pseudo-production environment

The key design choice is to defer hosted Kusto.

The API already supports JSON fallback telemetry, so early hosted testing should use that path and postpone a real analytics backend until there is enough traffic and feedback to justify it.

Hosted Responsibilities

Cloudflare Pages

Use Cloudflare Pages for the docs site.

Recommended settings:

  • Framework preset: None
  • Build command: pip install -r requirements-docs.txt && mkdocs build --clean
  • Build output directory: site
  • Root directory: repository root

This keeps official docs online at a public URL with no server maintenance.

Render

Use Render for the API and Admin applications.

The repository now includes a Render Blueprint in the root render.yaml file.

That blueprint defines:

  • echospire-api
  • echospire-admin

Both services build from the existing Dockerfiles in this repository.

For the current early-dev setup, the Admin service should call the API through the API's public Render HTTPS URL instead of the private-network service reference.

Neon

Use Neon for PostgreSQL.

What you need from Neon:

  • a database project
  • the pooled or direct PostgreSQL connection string

That connection string should be supplied to Render as ConnectionStrings__Postgres for the API service.

Upstash

Use Upstash for Redis.

What you need from Upstash:

  • a Redis database
  • the Redis connection string or host:port credential format needed by the API

That connection string should be supplied to Render as ConnectionStrings__Redis for the API service.

Telemetry Direction

Do not host Kusto in the early hosted setup.

Instead:

  • leave Telemetry__Kusto__ClusterUri empty
  • set Telemetry__JsonFallbackPath to a writable local path in the API container

The API now supports this cleanly and will skip Kusto initialization when no cluster URI is provided.

This is the right tradeoff for early dev because it preserves telemetry capture without forcing a paid analytics stack.

Render Blueprint Behavior

The Render Blueprint in the root render.yaml file is set up for:

  • Docker-based deploys for API and Admin
  • Admin-to-API communication over the API's public Render HTTPS URL for early-dev stability
  • generated JWT secret on first create
  • prompt-required values for Postgres, Redis, and AI API credentials
  • JSON fallback telemetry enabled

You should still review the environment variables in the Render Dashboard during first import.

Setup Order

Proceed in this order:

  1. Create the Neon project and copy the PostgreSQL connection string.
  2. Create the Upstash Redis instance and copy the Redis connection string.
  3. In Render, create a new Blueprint deployment from this repository.
  4. Provide the required environment variables for the API service.
  5. Let Render build and deploy the API and Admin services.
  6. In Cloudflare Pages, connect the same repository and configure the docs build.
  7. Point any custom domains once all default platform URLs are working.
  8. Build downloadable client artifacts for testers.

Required Render Values

The API service needs at least:

  • ConnectionStrings__Postgres
  • ConnectionStrings__Redis
  • AiCompletion__ApiKey if AI naming should be enabled

The Admin service uses the API service reference in the Blueprint and does not need a manually entered public API URL for the default hosted setup.

Immediate Checklist

For the first successful hosted deployment, the short checklist is:

  1. Stand up Neon.
  2. Stand up Upstash.
  3. Import the Blueprint into Render.
  4. Connect docs to Cloudflare Pages.
  5. Verify API health, Admin startup, and docs publication.
  6. Publish the ConsoleGame ZIP artifact for testers.

Later Migration Path

If early testing succeeds and more operational control is needed later, move from this hosted setup to one of these:

  • a single VM pseudo-production stack
  • managed Azure services
  • a more formal container platform

Nothing in this hosted path blocks that future move.