Deploy and Host SurfSense on Railway

SurfSense is a privacy-focused, open-source alternative to NotebookLM for individuals and teams. Upload PDFs, Office files and Markdown, capture web pages, connect Notion, Slack, Google Drive, Jira and more, then ask questions across everything with cited answers and turn your sources into reports, slide decks, podcasts and study material. You choose the model: OpenAI, Anthropic, OpenRouter, Azure, Ollama, LM Studio or any OpenAI-compatible endpoint.

About Hosting SurfSense

Hosting SurfSense means running a Next.js web app, a FastAPI backend with Celery background workers, Rocicorp Zero for real-time sync, PostgreSQL with pgvector and logical replication, and Redis, all behind one reverse proxy. This template mirrors upstream's docker/docker-compose.yml as six Railway services, with images pinned to the immutable git-a51f9a3 build. Only the Caddy gateway is public; it routes /api/v1, /auth and /zero over the private network exactly like upstream's Caddyfile. The API, Celery worker, Celery beat and migrations run together in one service (upstream's SERVICE_ROLE=all) because uploads are handed from the API to the worker as local files, and Railway volumes cannot be shared between services. Zero Cache waits for the migrations before it starts, the API binds a dual-stack socket, and Postgres runs with wal_level=logical.

Signup is protected. SurfSense lets anyone who reaches the URL register, and its own switch to turn that off also disables login. The gateway therefore asks for a generated signup password before anyone can open /register or create an account. Login and API tokens are unaffected.

Plan requirement: the API image is about 2.2 GB and loads PyTorch, Docling and a local embedding model, so use the Hobby plan or higher. The first deploy takes several minutes.

Upstream note: SurfSense's maintainers now recommend their desktop app for new users; the self-hosted web stack remains open source and community supported. SurfSense is Apache-2.0 except a BSL-1.1 scraper module, which may be used in production but not resold as a hosted service.

Common Use Cases

Private NotebookLM for a team: shared workspaces over your own documents, with your own model keys
Research assistant: cited answers across papers, notes, captured web pages and connected tools
Knowledge base over SaaS tools: index Notion, Slack, Google Drive, Gmail, Jira, Linear, Confluence and more
Content from sources: summaries, reports, slide decks and two-host podcasts generated from selected documents
Local model friendly: point it at Ollama, LM Studio or vLLM; parsing and embeddings already run locally

Dependencies for SurfSense Hosting

PostgreSQL 17 with pgvector: included, with logical replication enabled for Zero
Redis: included, Celery broker and cache
Rocicorp Zero: included, real-time sync
A model provider: not needed to boot; add one after deploy under Workspace Settings, Models
No GPU required: Docling parsing, MiniLM embeddings, Kokoro TTS and Whisper STT run on CPU

Deployment Dependencies

Implementation Details

First steps after deploy:

Wait until all six services are green (Zero Cache turns green after the API finishes its migrations)
Copy SIGNUP_PASSWORD from the SurfSense service, Variables tab
Open https:///register, enter admin and that password in the browser prompt, then create your account
Open Workspace Settings, Models and add a provider key or a local model server URL
Upload a document or add a note and start asking questions

Key variables:

# SurfSense (gateway, public)
PORT=8080
SIGNUP_USERNAME=admin
SIGNUP_PASSWORD=${{secret(24)}}
WEB_UPSTREAM=${{SurfSense Web.RAILWAY_PRIVATE_DOMAIN}}:3000
API_UPSTREAM=${{SurfSense API.RAILWAY_PRIVATE_DOMAIN}}:8000
ZERO_UPSTREAM=${{Zero Cache.RAILWAY_PRIVATE_DOMAIN}}:4848

# SurfSense API
PORT=8000
SERVICE_ROLE=all
SECRET_KEY=${{secret(64)}}
DATABASE_URL=postgresql+asyncpg://${{Postgres.POSTGRES_USER}}:${{Postgres.POSTGRES_PASSWORD}}@${{Postgres.RAILWAY_PRIVATE_DOMAIN}}:5432/${{Postgres.POSTGRES_DB}}
REDIS_URL=${{Redis.REDIS_URL}}
SURFSENSE_PUBLIC_URL=https://${{SurfSense.RAILWAY_PUBLIC_DOMAIN}}
REGISTRATION_ENABLED=TRUE
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
SANDBOX_ENABLED=FALSE
FILE_STORAGE_LOCAL_PATH=/data/object_store

# SurfSense Web
PORT=3000
HOSTNAME=::
SURFSENSE_BACKEND_INTERNAL_URL=http://${{SurfSense API.RAILWAY_PRIVATE_DOMAIN}}:8000
ZERO_QUERY_API_KEY=${{Zero Cache.ZERO_QUERY_API_KEY}}

# Zero Cache
ZERO_UPSTREAM_DB=postgresql://...@${{Postgres.RAILWAY_PRIVATE_DOMAIN}}:5432/surfsense?sslmode=disable
ZERO_APP_PUBLICATIONS=zero_publication
ZERO_QUERY_URL=http://${{SurfSense Web.RAILWAY_PRIVATE_DOMAIN}}:3000/api/zero/query

Keep REGISTRATION_ENABLED=TRUE (in SurfSense, FALSE also blocks login). Set EMBEDDING_MODEL once: changing it after documents are indexed breaks the vector dimensions. The code execution sandbox is off because upstream's sandbox server needs the Docker socket; set SANDBOX_PROVIDER=daytona with a Daytona key to enable it.

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 get a complete self-hosted research workspace with Postgres, pgvector, Redis and real-time sync wired together over private networking, generated secrets, persistent volumes, healthchecks, a gated signup, and managed SSL on one public domain.