Ramaris Ramaris Docs
Back to App

Admin / Ops

This section is for operators and developers running Ramaris in development or production environments. It is public for now, but the content is ops-focused.

What this covers

  • Service topology (frontend + backend + worker)
  • Environment configuration (what needs to exist and where)
  • Operational runbooks (Redis/worker schedules, telemetry, troubleshooting)
  • High-signal debugging checklists

Architecture quick map

Ramaris is a three-component system:

  • Frontend (React + Vite + TypeScript + Tailwind)
    • UI, routing, PWA service worker, push subscription UX
  • Backend (Node.js / Express / tRPC / Prisma)
    • API, auth, user & strategy management, notifications pipeline
    • Hosts the block relay WebSocket that the UI connects to
  • Worker (Go)
    • Ingests on-chain/provider data, runs grading loops, emits events into Redis

For diagrams and deep flows, see the repo docs links below.

Runbooks & operational docs (existing)

Use these existing docs as the authoritative ops references:

  • Redis + Worker Operations
    • docs/RUNBOOK-REDIS-WORKER.md
  • Telemetry / Observability
    • docs/TELEMETRY.md
    • docs/SIGNOZ-QUERIES.md
  • General Troubleshooting
    • docs/TROUBLESHOOTING.md
  • Realtime / scaling notes
    • docs/realtime-scaling-architecture.md

Environment configuration (high level)

Ramaris typically needs:

  • PostgreSQL (Supabase) via DATABASE_URL
  • Redis via REDIS_URL
  • RPC / Provider APIs (worker + backend, depending on features)
  • HTTPS in production for PWA + push notifications

See root README.md for the current .env templates and required variables.

Common operational checks (high signal)

1) Is the API reachable?

  • Open DevTools → Network and confirm requests to /api/* return 2xx (or meaningful 4xx/5xx)
  • If you see Failed to fetch, confirm:
    • backend process is running
    • correct ports / proxy target
    • no VPN/corp proxy blocking

2) Is Redis reachable and healthy?

  • Worker depends on Redis for schedules/quotas/event coordination.
  • If worker loops appear stuck, check the Redis runbook and confirm keys/schedules are present.

3) Is the worker running?

  • Worker should be connected to Redis and Postgres and emitting events.
  • If the UI shows no realtime updates, confirm worker logs show successful loop cycles.

4) Is telemetry exporting?

  • If you expect SigNoz data, confirm exporter endpoints and environment variables per docs/TELEMETRY.md.

Deployments (notes)

Deployment strategy varies by environment, but ops best practices apply:

  • Treat the worker as a long-running process with restart policy.
  • Keep backend and worker secrets out of the frontend build.
  • For production, ensure:
    • HTTPS is correctly configured
    • service worker scope is correct
    • CORS/cookies/auth behave as expected

Incident checklist (quick)

  1. Identify which component is failing: UI, backend API, worker loops, Redis, Postgres.
  2. Look for:
    • backend logs (tRPC errors, Prisma errors, auth/cookie issues)
    • worker logs (provider quota errors, Redis scheduling issues)
    • DB connectivity errors
  3. Use the docs above as the primary runbooks and reference material.

Where to go next

  • User-facing docs: /docs/, /docs/create-strategy/
  • Ops runbooks: see the docs/* files linked above