feat(self-host): align Docker Compose with Helm and overhaul self-hosting docs (#6225)

* feat(self-host): align Docker Compose with Helm and overhaul self-hosting docs

Docker Compose shipped no scheduler, so scheduled workflows, every polling
trigger, connector syncs, the outbox, and data drains silently never ran.
Adds a cron service running the same 18 jobs the Helm chart schedules as
CronJobs, and closes the remaining behavioral gaps between the two paths:
bundled Redis in the chart, no hosted plan caps in chart defaults, pinned
image tags, and fail-fast secrets. A CI check keeps the schedulers in sync.

Also rewrites the self-hosting docs: 14 new pages, 8 updated, reorganized
into Install / Configure / Operate.

* fix(self-host): drop bun install from chart CI, remove air-gapped and backup docs

The scheduler-parity check pulled a full dependency install into the
chart-validation job, which fails building isolated-vm on that runner.
Rewritten to use only node builtins so the job installs nothing.

Also removes the air-gapped and backup/restore pages, and stops pinning a
concrete release in the docs so the examples do not go stale each release.

* fix(helm): bundle Redis in secret-manager modes unless the URL is supplied

Suppressing Redis whenever a secret mode was active left those deployments
with no Redis at all — REDIS_URL is optional there and both shipped examples
omit it. The chart now steps aside only on a detectable signal: an explicit
app.env.REDIS_URL, an ESO remoteRefs.app.REDIS_URL mapping, or the new
redis.provideUrl=false opt-out for a pre-created Secret it cannot read.

* fix(compose): derive realtime BETTER_AUTH_URL from NEXT_PUBLIC_APP_URL

realtime read BETTER_AUTH_URL directly and fell back to localhost while
simstudio derived it from NEXT_PUBLIC_APP_URL, so setting only the public
origin left realtime authenticating against http://localhost:3000.

* fix(helm): deliver bundled REDIS_URL via ConfigMap so an operator value always wins

Injecting REDIS_URL as an inline container env made it beat every envFrom
source, so a REDIS_URL held in a pre-created Secret or synced by External
Secrets was silently shadowed and traffic moved to a fresh in-cluster Redis.

Kubernetes resolves duplicate envFrom keys by letting the last source win, so
the bundled URL now ships as a ConfigMap listed before the app Secret. Any
operator-supplied value overrides it without the chart needing to read it,
which also removes the redis.provideUrl flag the previous attempt required.

* docs(helm): spell out the egress rule external datastores need

The default NetworkPolicy allows 443 plus the bundled Postgres and Redis by
pod selector. Anything you run outside the chart on another port needs its own
rule, which is easiest to miss when REDIS_URL arrives via a Secret the chart
cannot inspect. Adds a copyable example to the production checklist and the
security guide.

* feat(helm): add networkPolicy.allowExternalEgress for managed datastores

The default policy allows 443 plus the bundled Postgres and Redis by pod
selector, so a managed datastore on another port needs a hand-written CIDR
rule — awkward when REDIS_URL arrives via a Secret the chart cannot inspect.

Adds an opt-in switch that drops the port restriction while still blocking the
cloud metadata endpoints. Defaults to false, keeping this chart stricter than
the common chart default of unrestricted egress.

.github/CONTRIBUTING.md

@@ -165,6 +165,15 @@ After running this command, open [http://localhost:3000/](http://localhost:3000/
 git clone https://github.com/<your-username>/sim.git
 cd sim
 
+# Generate the required secrets. The stack refuses to start without them
+# rather than booting with empty values.
+cat > .env << EOF
+BETTER_AUTH_SECRET=$(openssl rand -hex 32)
+ENCRYPTION_KEY=$(openssl rand -hex 32)
+INTERNAL_API_SECRET=$(openssl rand -hex 32)
+CRON_SECRET=$(openssl rand -hex 32)
+EOF
+
 # Start Sim
 docker compose -f docker-compose.prod.yml up -d
 ```

.github/workflows/ci.yml

@@ -294,6 +294,12 @@ jobs:
             ecr_repo_secret: ECR_PII
             gh_runner: ubuntu-latest
             bs_runner: blacksmith-4vcpu-ubuntu-2404
+          # No ECR repo is provisioned for cron, so it publishes to GHCR only.
+          # The tag step below omits the ECR tag when the repo name is empty.
+          - dockerfile: ./docker/cron.Dockerfile
+            ghcr_image: ghcr.io/simstudioai/cron
+            gh_runner: ubuntu-latest
+            bs_runner: blacksmith-2vcpu-ubuntu-2404
     steps:
       - name: Checkout code
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
@@ -338,15 +344,33 @@ jobs:
           ECR_REPO="${{ steps.ecr-repo.outputs.name }}"
           GHCR_IMAGE="${{ matrix.ghcr_image }}"
 
-          TAGS="${ECR_REGISTRY}/${ECR_REPO}:${{ github.sha }}"
+          TAGS=""
+          if [ -n "$ECR_REPO" ]; then
+            TAGS="${ECR_REGISTRY}/${ECR_REPO}:${{ github.sha }}"
+          fi
 
           if [ "${{ github.ref }}" = "refs/heads/main" ] && [ -n "$GHCR_IMAGE" ]; then
-            TAGS="${TAGS},${GHCR_IMAGE}:${{ github.sha }}-amd64"
+            if [ -n "$TAGS" ]; then
+              TAGS="${TAGS},${GHCR_IMAGE}:${{ github.sha }}-amd64"
+            else
+              TAGS="${GHCR_IMAGE}:${{ github.sha }}-amd64"
+            fi
+          fi
+
+          # An entry can legitimately resolve to no tags — e.g. the cron image has
+          # no ECR repo, so on staging/dev (where GHCR tags are not applied) there
+          # is nothing to push. Skip that build instead of failing the job.
+          if [ -z "$TAGS" ]; then
+            echo "No ECR repo and no GHCR tag for this entry on ${{ github.ref }} — skipping push."
+            echo "skip=true" >> $GITHUB_OUTPUT
+          else
+            echo "skip=false" >> $GITHUB_OUTPUT
           fi
 
           echo "tags=${TAGS}" >> $GITHUB_OUTPUT
 
       - name: Build and push images
+        if: steps.meta.outputs.skip != 'true'
         uses: ./.github/actions/docker-build
         with:
           provider: ${{ vars.CI_PROVIDER }}
@@ -470,6 +494,10 @@ jobs:
             image: ghcr.io/simstudioai/pii
             gh_runner: ubuntu-24.04-arm
             bs_runner: blacksmith-4vcpu-ubuntu-2404-arm
+          - dockerfile: ./docker/cron.Dockerfile
+            image: ghcr.io/simstudioai/cron
+            gh_runner: ubuntu-24.04-arm
+            bs_runner: blacksmith-4vcpu-ubuntu-2404-arm
 
     steps:
       - name: Checkout code
@@ -515,6 +543,7 @@ jobs:
           - image: ghcr.io/simstudioai/migrations
           - image: ghcr.io/simstudioai/realtime
           - image: ghcr.io/simstudioai/pii
+          - image: ghcr.io/simstudioai/cron
 
     steps:
       - name: Login to GHCR

.github/workflows/helm.yml

@@ -32,6 +32,17 @@ jobs:
         with:
           version: v3.16.4
 
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: 1.3.13
+
+      # Docker Compose and Kubernetes must run the same background jobs on the
+      # same schedules; this fails the build if the two drift apart. The script
+      # imports only node builtins, so this job installs no dependencies.
+      - name: Scheduler parity (docker/crontab vs helm cronjobs)
+        run: bun run scripts/check-cron-parity.ts
+
       - name: Helm lint
         run: helm lint helm/sim --values helm/sim/ci/default-values.yaml