Deploy and Host SurfSense on Railway

SurfSense is an open-source AI research agent and NotebookLM alternative. It connects your personal knowledge base to search engines, Slack, Notion, Gmail, GitHub, and 15+ other sources, letting you chat with your documents, generate podcasts, and run deep research agents — all on your own infrastructure with your own LLM keys.

About Hosting SurfSense

SurfSense is a six-service stack: a FastAPI backend (which also runs Alembic migrations, a Celery worker, and Celery beat), a Next.js frontend, Postgres with pgvector and logical replication enabled, Redis as the Celery broker, a Zero sync engine for real-time UI updates, and a Caddy proxy that serves everything from a single public origin — required for session cookies and Zero's websocket paths. This template wires all of it together with private networking, persistent volumes for Postgres, uploaded files, and the Zero replica, and generated secrets. First boot takes ~15–20 minutes while the backend image pulls and migrations run; zero-cache restarting during that window is expected and self-heals.

Common Use Cases

Private, self-hosted NotebookLM alternative: upload documents (50+ file formats) and chat with them using your own LLM API keys, with cited answers
Team research hub that indexes Slack, Notion, Jira, Linear, Gmail, Google Drive, GitHub, and more into one searchable, agent-accessible knowledge base
Content generation from your knowledge base: podcasts with local TTS, deep research reports, and browser-extension capture of pages you visit

Dependencies for SurfSense Hosting

An LLM provider API key (OpenAI, Anthropic, Gemini, or any LiteLLM-compatible provider) — configured in the app after signup
Nothing else: document parsing (Docling), embeddings (sentence-transformers), TTS (Kokoro), and STT (Faster-Whisper) all run locally by default

Deployment Dependencies

Implementation Details

Single public origin. Only the Caddy proxy is exposed. It routes /auth, /users, and /api/v1 to the backend, /zero/* to the Zero sync engine (websockets), and everything else to the frontend — mirroring the upstream production Caddyfile. The full Caddy config lives in the proxy service's CADDYFILE variable, so you can edit routing without rebuilding an image.

Combined backend roles. The backend container runs with SERVICE_ROLE=all (migrations + API + Celery worker + beat), because the API and worker exchange uploaded files through a shared temp directory:

SERVICE_ROLE=all   # migrate → api + worker + beat in one container

Postgres with logical replication. The database starts with wal_level=logical and replication slots enabled — required by Zero. The zero_publication is created automatically by the backend's migrations on first boot; zero-cache waits (crash-looping by design, restart policy ALWAYS) until it exists.

Secrets. Postgres password, backend SECRET_KEY, Zero admin password, and the zero-cache↔frontend API key are generated per deploy; every cross-service value is wired with reference variables (e.g. ${{db.POSTGRES_PASSWORD}}), so nothing needs manual configuration.

Why Deploy SurfSense on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying SurfSense on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.