Skip to content

docs: add self-hosting guide#1660

Merged
Uarmagan merged 1 commit intomainfrom
docs/add-self-hosting-docs
Apr 21, 2026
Merged

docs: add self-hosting guide#1660
Uarmagan merged 1 commit intomainfrom
docs/add-self-hosting-docs

Conversation

@Uarmagan
Copy link
Copy Markdown
Contributor

Summary

Adds the first pass of Compass self-hosting documentation and clarifies the difference between local development setup and product hosting/account modes.

This PR is docs-only. It intentionally does not implement the future one-command installer; that will happen in a follow-up branch.

What changed

  • Added a short README entry point for self-hosting.
  • Added docs/self-hosting.md for people manually setting up Compass today.
  • Added docs/development/hosting-modes.md for contributors to understand hosting context, account state, and data ownership.
  • Renamed docs/development/env-and-dev-modes.md to docs/development/local-development.md so local developer setup is not confused with hosting modes.
  • Updated docs index and onboarding links to use the new names.
  • Added docs/superpowers/ to .gitignore so future brainstorming/design drafts do not get committed by default.

Why

We identified two separate audiences that needed different docs:

  • People self-hosting Compass need practical setup guidance: what services they provide, what Compass provides, how to start the app, and where their data lives.
  • Contributors need a mental model for how Compass behaves across anonymous browser use, self-hosted account mode, and hosted Compass Cloud.

Splitting those concerns keeps the public self-hosting guide approachable while still giving contributors the deeper map they need.

Important behavior captured

  • Anonymous users can use Compass without an account; events and tasks stay in browser IndexedDB.
  • After signup, local events migrate to the MongoDB configured for that backend.
  • Tasks currently stay in IndexedDB even after signup.
  • Self-hosted account mode needs MongoDB and SuperTokens.
  • Google Calendar sync is optional as a product behavior, but the backend currently still requires Google env values at startup.
  • Server deployments need public web/API URLs, HTTPS, correct FRONTEND_URL / BASEURL / CORS, and MongoDB/SuperTokens reachable from the backend.

Validation

  • Checked local markdown links in the touched docs.
  • Reviewed the branch diff against main to ensure this branch is docs-focused.
  • Moved the work from the earlier misleading feat/one-cmd-dev-setup branch to docs/add-self-hosting-docs; the actual installer work will be handled separately.

Follow-up work

@Uarmagan Uarmagan force-pushed the docs/add-self-hosting-docs branch from 858340d to 6fddacd Compare April 21, 2026 15:42
Add the public self-hosting guide and contributor-facing hosting modes map. Rename the local development guide so developer setup is not confused with hosting/account modes, and ignore future Superpowers design drafts.
@Uarmagan Uarmagan force-pushed the docs/add-self-hosting-docs branch from 6fddacd to f0be309 Compare April 21, 2026 15:49
@Uarmagan Uarmagan merged commit c50c23c into main Apr 21, 2026
4 of 8 checks passed
@Uarmagan Uarmagan deleted the docs/add-self-hosting-docs branch April 21, 2026 21:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant