Skip to content

self-hosting.md

Latest commit

 

History

History
108 lines (78 loc) · 3.06 KB

self-hosting.md

File metadata and controls

108 lines (78 loc) · 3.06 KB

Pulse Self-Hosting Notes

The root README.md is the primary deployment guide and now contains the full Docker, Docker Compose, Railway, rollout-order, and Telegram session instructions.

Use this document as a short companion for environment-specific notes that should stay aligned with the checked-in deployment artifacts.

Docker Compose

Default stack:

docker compose up -d

Optional profiles:

docker compose --profile seed run --rm db-seed
docker compose --profile near up -d near-balance-listener
docker compose --profile telegram up -d telegram-listener

Useful checks:

docker compose ps
docker compose logs -f web the-brain discourse-listener
curl http://127.0.0.1:3000/healthz

Key behavior:

  • db-migrate runs automatically before any long-running service starts.
  • db-seed is opt-in and should stay out of production rollouts.
  • PostgreSQL is exposed to the host on port 55432 by default.
  • Telegram session state is stored in the telegram_session named volume.

Single VM / Bare Metal

  1. Install Node.js 20+, pnpm, Rust, and PostgreSQL.
  2. Clone the repo, create .env, and fill in production values.
  3. Run migrations before starting services:
pnpm install
pnpm db:migrate:latest
pnpm db:generate
  1. Seed only when you explicitly want the demo/bootstrap data:
pnpm db:seed:run
  1. Build the deployable services:
pnpm build:shared
pnpm build:better-auth-near
pnpm build:web
pnpm build:the-brain
pnpm build:rust
  1. Run the services under systemd, pm2, or another supervisor.

Suggested long-running processes:

  • pnpm start
  • pnpm the-brain:start
  • cd apps/discourse-listener && cargo run --release
  • cd apps/telegram-listener && cargo run --release
  • cd apps/near-balance-listener && cargo run --release

Railway

Long-running services already have committed Railway manifests:

  • apps/web/railway.toml
  • apps/the-brain/railway.toml
  • apps/discourse-listener/railway.toml
  • apps/telegram-listener/railway.toml
  • apps/near-balance-listener/railway.toml

Recommended rollout:

  1. Provision PostgreSQL.
  2. Run migrations separately with npx kysely migrate latest or a one-off service based on migrations/Dockerfile.
  3. Deploy web and verify /healthz.
  4. Deploy the-brain and verify /health.
  5. Deploy only the listener workers you need.

Railway-specific notes:

  • web uses /healthz, not /api/health.
  • the-brain expects port 3001 for its health server.
  • Rust listeners are worker services and should not rely on HTTP health checks.
  • For Telegram on Railway, prefer TELEGRAM_SESSION_DATA unless you attach durable storage.

Production Checklist

  • Use strong random values for BETTER_AUTH_SECRET and FLAGS_SECRET.
  • Keep DEV_AUTH_BYPASS=false in any non-local environment.
  • Run db-migrate before every schema-dependent deploy.
  • Keep Telegram session material in durable storage or TELEGRAM_SESSION_DATA.
  • Schedule PostgreSQL backups and monitor worker logs.
  • Review docs/environment.md before promoting any environment to production.