feat(self-host): align Docker Compose with Helm and overhaul self-hosting docs - #6225
Conversation
…ting 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.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
PR SummaryMedium Risk Overview Helm 1.5.0 bundles Redis by default (existing CI builds/publishes Docs & onboarding add many self-hosting guides (architecture, auth, email, Redis, networking, security, scaling, upgrades, verify, integrations OAuth, etc.), refresh Docker/Kubernetes/env-var pages, and document generating secrets including Reviewed by Cursor Bugbot for commit a95c90f. Configure here. |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Greptile SummaryThe PR aligns Docker Compose background scheduling and Redis behavior with Helm while substantially expanding self-hosting operational documentation.
Confidence Score: 4/5The PR should not merge until the existing NetworkPolicy failure for Secret-selected external Redis is resolved or made safe by default. The current app and realtime policies permit Redis traffic only to the bundled pod selector and otherwise allow external traffic on port 443, so an external Redis selected through a Secret remains unreachable on standard Redis ports unless operators independently add a custom egress rule; the prior reply documents this residual requirement rather than removing it. Files Needing Attention: helm/sim/templates/networkpolicy.yaml
|
| Filename | Overview |
|---|---|
| helm/sim/templates/_helpers.tpl | Revises bundled Redis selection so secret-manager modes retain a safe fallback while direct app.env.REDIS_URL values suppress it. |
| helm/sim/templates/configmap-redis.yaml | Provides the bundled Redis URL through an earlier envFrom source so operator Secrets can override it. |
| helm/sim/templates/networkpolicy.yaml | Adds bundled Redis egress rules, while external Redis selected through a Secret still requires a manually configured egress rule. |
| helm/sim/values.schema.json | Adds Redis configuration schema, but its secret-manager suppression description disagrees with the current helper behavior. |
| docker-compose.prod.yml | Adds Redis and cron services, image version controls, and required-secret validation for the Compose deployment. |
| docker/crontab | Defines the Compose schedules corresponding to Helm CronJobs. |
| scripts/check-cron-parity.ts | Adds CI validation that Compose and Helm scheduler endpoints and schedules remain aligned. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart LR
Scheduler[Compose cron / Helm CronJobs] -->|Bearer CRON_SECRET| App[Sim app]
App --> Postgres[(PostgreSQL)]
App --> RedisChoice{REDIS_URL source}
RedisChoice -->|Bundled ConfigMap| Bundled[(Bundled Redis)]
RedisChoice -->|Later Secret override| External[(External Redis)]
Realtime[Realtime] --> RedisChoice
Reviews (6): Last reviewed commit: "feat(helm): add networkPolicy.allowExter..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
… 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.
…plied 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.
|
@cursor review |
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.
|
@cursor review |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 58bd1ba. Configure here.
…ue 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.
|
@cursor review |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit d2f7e2c. Configure here.
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.
|
@cursor review |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit ee2d004. Configure here.
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.
|
Added The default policy allows 443 plus the bundled Postgres and Redis by pod selector, so any datastore running outside the chart on another port needs a hand-written CIDR rule. That is awkward precisely in the case raised — a networkPolicy:
enabled: true
allowExternalEgress: true # drops the port restrictionCloud metadata endpoints ( Defaults to Verified: 443-only by default, unrestricted when enabled, metadata blocked in both; kubeconform clean in both modes; 97 chart tests. |
|
@cursor review |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit a95c90f. Configure here.
|
On the remaining 4/5 — I want to push back on the "safe by default" framing with the actual defaults, because I think it rests on a factual error.
So no default install is affected by this. Reaching the scenario requires an operator to deliberately set Two further points:
What this PR does provide, for an operator who has opted into NetworkPolicy and runs a managed datastore: a copyable CIDR rule in both the production checklist and the security guide, and I am treating this as a deliberate posture rather than an unresolved defect, and leaving the default strict. Happy to revisit if a maintainer prefers the permissive default. |
1 participant
Summary
cronservice to Docker Compose running the same 18 background jobs the Helm chart schedules as CronJobs. Scheduled workflows, every polling trigger, connector syncs, the outbox, and data drains previously never ran on Compose — silently, with no errorredis.enabled, chart 1.4.0 → 1.5.0) to match Compose. An existingapp.env.REDIS_URL,existingSecret, or External Secrets config takes precedence and suppresses the bundled instance, so upgrading a release that points at a managed Redis renders unchangedapp.envDefaults. With billing disabled these are opt-in — presetting them enforced hosted limits on self-hosters and diverged from Compose, which presets nothingSIM_VERSIONand made missing secrets fail loudly instead of booting with empty values.CRON_SECRETdegrades gracefully (cron exits with instructions, rest of the stack runs) so deployments predating the scheduler still startscripts/check-cron-parity.tsto CI sodocker/crontaband the Helm CronJobs can't drift apartThe docs work started as a gap analysis against a hand-written customer runbook. Most of the gaps turned out to be product inconsistencies rather than missing docs, which is what the rest of this PR fixes.
Type of Change
Testing
Tested manually. Brought the full Compose stack up end to end — all six services healthy, 11/11 minute-cadence jobs succeeded against the live app, zero failures. Verified
CRON_SECRETreturns 401 when wrong or absent, and that an existing.envwithout it still starts with the scheduler self-disabling.Helm: 98 unit tests (5 new for Redis modes),
helm lint, kubeconform strict on default and all-components, all 10 example values files render. Verified upgrade paths render unchanged for managed Redis,existingSecret, External Secrets, and explicitly set plan limits.Checklist
Note for reviewers:
ghcr.io/simstudioai/crondoes not exist until this lands onmainand CI publishes it. The compose file has abuild:fallback soup -dworks from a clone in the meantime, butdocker compose pullwill report it missing until then.docker-compose.ollama.ymlwas deliberately left untouched — it has no cron service and no fail-fast secrets, so it's now inconsistent withdocker-compose.prod.yml. Worth a follow-up.