Upgrade self host docs + migrate docs - #2847
Conversation
📝 WalkthroughWalkthroughAdded overview, VPS, AWS, and Instant Cloud migration guides for self-hosting. Updated documentation navigation to group these guides under a dedicated self-hosting section. ChangesSelf-hosting documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (5)
client/www/app/docs/self-hosting/aws/page.md (4)
151-167: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick winInclude
INSTANT_SUPERUSER_EMAILin the shared backend configuration.Add this variable to the minimum environment block, or link directly to the operating step before deployment. State that changes require a rolling restart. Based on learnings,
INSTANT_SUPERUSER_EMAILis the authoritative deployment-superuser setting, and startup reconciles Instant Config ownership to that email.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@client/www/app/docs/self-hosting/aws/page.md` around lines 151 - 167, Update the minimum environment configuration block to include INSTANT_SUPERUSER_EMAIL, identifying it as the authoritative deployment-superuser setting; mention that changing it requires a rolling restart and that startup reconciles Instant Config ownership to this email.Source: Learnings
40-43: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd a language identifier to this fenced block.
markdownlintreports MD040 for this AWS CLI block. Mark it asshell.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@client/www/app/docs/self-hosting/aws/page.md` around lines 40 - 43, Add the shell language identifier to the fenced code block containing the AWS CLI commands, without changing the commands themselves, so the markdown passes MD040.Source: Linters/SAST tools
136-138: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd language identifiers to the fenced blocks.
markdownlintreports MD040 for these blocks. Addshellfor command and environment blocks, andtextfor image names, paths, DNS names, and URLs.Also applies to: 147-149, 153-167, 177-179, 183-185, 204-206, 210-212, 216-218
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@client/www/app/docs/self-hosting/aws/page.md` around lines 136 - 138, Add language identifiers to every fenced code block in the self-hosting AWS documentation, including the blocks around the shown image name and all referenced ranges. Use shell for commands or environment-variable examples, and text for image names, paths, DNS names, and URLs, without changing the block contents.Source: Linters/SAST tools
120-123: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winPin the image release used for configuration and deployment.
server:latestis used to generateoverride.ednand run the backend.dashboard:latestis also floating. Restarts or scale-outs can pull different releases, and the generated configuration can come from a different server version. Use one release tag or digest for related images and upgrade deliberately.Also applies to: 134-138, 202-206
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@client/www/app/docs/self-hosting/aws/page.md` around lines 120 - 123, Update the AWS self-hosting instructions to replace floating server:latest and dashboard:latest references with one explicit release tag or digest shared by the related images, including the configuration-generation command and backend deployment commands. Ensure all affected image references use the same pinned version so upgrades are deliberate.client/www/app/docs/self-hosting/migrate/page.md (1)
105-113: 🗄️ Data Integrity & Integration | 🔵 TrivialDefine the rollback procedure before merging the client cutover.
After the first self-hosted write, the Instant Cloud copy is stale. If validation fails, the guide does not provide a safe recovery path. Document whether cutover is irreversible and how operators recover without creating two divergent writable copies.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@client/www/app/docs/self-hosting/migrate/page.md` around lines 105 - 113, Update the “Switch to self-hosted Instant” section to define the rollback procedure before instructing operators to merge the client cutover. State whether the first self-hosted write makes the migration irreversible, and provide a safe recovery path that avoids treating both self-hosted Instant and Instant Cloud as writable sources or creating divergent copies.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@client/www/app/docs/self-hosting/aws/page.md`:
- Around line 140-142: Update the self-hosting deployment guidance to place
backend tasks across at least two Availability Zones instead of co-locating both
tasks with the Aurora writer. Retain the load balancer routing and
/health/system health-check instructions while specifying the scheduler
placement requirement.
- Around line 61-69: Update the AWS self-hosting database configuration and
DATABASE_URL documentation to require TLS for backend connections, while
isolating the necessary rds.force_ssl = 0 exception to Instant’s migration
connection only. Document the migration-specific plaintext requirement and
ensure port 5432 remains restricted to backend servers; do not present plaintext
as the general production database configuration.
In `@client/www/app/docs/self-hosting/migrate/page.md`:
- Around line 84-91: Replace the fixed 30-second wait in the “Pause writes on
Instant Cloud” migration instructions with an observable quiescence check.
Direct users to wait for the service’s verified indication that all accepted
in-flight mutations have completed before starting the final backup, while
preserving the existing read-only behavior and scope.
In `@client/www/app/docs/self-hosting/page.md`:
- Around line 33-34: Update the self-hosting guide’s Postmark fallback section
in client/www/app/docs/self-hosting/page.md:33-34 to require Postmark before
production and document strict log access control, short retention, and no
forwarding to shared logs. Also update the login-code logging guidance in
client/www/app/docs/self-hosting/vps/page.md:123-128 to warn that tailed logs
contain authentication secrets and must not be used as the normal production
login flow.
---
Nitpick comments:
In `@client/www/app/docs/self-hosting/aws/page.md`:
- Around line 151-167: Update the minimum environment configuration block to
include INSTANT_SUPERUSER_EMAIL, identifying it as the authoritative
deployment-superuser setting; mention that changing it requires a rolling
restart and that startup reconciles Instant Config ownership to this email.
- Around line 40-43: Add the shell language identifier to the fenced code block
containing the AWS CLI commands, without changing the commands themselves, so
the markdown passes MD040.
- Around line 136-138: Add language identifiers to every fenced code block in
the self-hosting AWS documentation, including the blocks around the shown image
name and all referenced ranges. Use shell for commands or environment-variable
examples, and text for image names, paths, DNS names, and URLs, without changing
the block contents.
- Around line 120-123: Update the AWS self-hosting instructions to replace
floating server:latest and dashboard:latest references with one explicit release
tag or digest shared by the related images, including the
configuration-generation command and backend deployment commands. Ensure all
affected image references use the same pinned version so upgrades are
deliberate.
In `@client/www/app/docs/self-hosting/migrate/page.md`:
- Around line 105-113: Update the “Switch to self-hosted Instant” section to
define the rollback procedure before instructing operators to merge the client
cutover. State whether the first self-hosted write makes the migration
irreversible, and provide a safe recovery path that avoids treating both
self-hosted Instant and Instant Cloud as writable sources or creating divergent
copies.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 6583eda9-4f70-4eb5-8727-f46860ba01fb
📒 Files selected for processing (5)
client/www/app/docs/self-hosting/aws/page.mdclient/www/app/docs/self-hosting/migrate/page.mdclient/www/app/docs/self-hosting/page.mdclient/www/app/docs/self-hosting/vps/page.mdclient/www/data/docsNavigation.js
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@client/www/app/docs/self-hosting/page.md`:
- Line 8: Update the user-facing introduction in the self-hosting documentation
to hyphenate “self hosting” as “self-hosting,” matching the existing
“self-hosted” terminology.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 8d144d8f-aaff-4260-b2c6-a5181621fbe6
📒 Files selected for processing (1)
client/www/app/docs/self-hosting/page.md
|
View Vercel preview at instant-www-js-self-host-docs-jsv.vercel.app. |
2 participants
Previously we just had one page for self-hosting but now we'll split this into it's own section!
Overview
We'll now have an overview page that links out to individual guides for hosting on VPS (intended for side-projects, ~$30/mo via DO) and AWS (intended for serious projects, ~$600/mo)
The overview page also includes a section on operating the self hosted deployment. This includes info on deployment settings (restricting signups, restricting temporary apps), using cli tools, and call-outs about hazelcast and memory limits. The individual VPS and AWS guides also have more info on how to scale those deployments.
VPS/AWS Guides
The goal of the VPS and AWS docs is to give enough context for both a human and an agent to understand what needs to happen without being overly prescriptive. The VPS docs are based on what we had before for self-hosting. I made these by iterating on the flow with codex and patching places where it got confused (Hazelcast, S3 CORS, etc). I tested both guides from a fresh codex session and got them working!
In both the VPS/AWS guides I include general advice on scaling up instances/db. For AWS I also include our current AWS configuration
Simplifications
Finally I thought it would be better to cut some things. I removed the following: