---
title: "Deploy SurfSense Research"
description: "SurfSense research notebook with document search, cited chat and login"
category: "AI/ML"
url: https://railway.com/deploy/surfsense-research
---

# Deploy SurfSense Research

SurfSense research notebook with document search, cited chat and login

**[Deploy SurfSense Research on Railway](https://railway.com/template/surfsense-research)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/surfsense-research/manifest.json

- **Creator:** Anton Orel's Projects
- **Category:** AI/ML
- **Total deploys:** 6

## Template content

### SurfSense

- **Image:** ghcr.io/modsetter/surfsense:2.3.1@sha256:106baa89d5f79168c1c5e9bce77655d3e99f2950250772a1d41508c04d73a4a0
- **Start command:** `/bin/sh -ec 'n=$(printf %s "${SURFSENSE_PASSWORD:-}" | LC_ALL=C.UTF-8 wc -m) || n=0; if ! [ "$n" -ge 16 ]; then echo "SurfSense refused to start: SURFSENSE_PASSWORD must stay set to 16 or more characters" >&2; exit 64; fi; if [ -n "${SURFSENSE_AUTH:-}" ]; then echo "SurfSense refused to start: SURFSENSE_AUTH must stay unset, because the password is all that guards the public domain" >&2; exit 64; fi; if [ -n "${SURFSENSE_TLS:-}${SURFSENSE_DOMAIN:-}" ]; then echo "SurfSense refused to start: Railway terminates HTTPS, so SURFSENSE_TLS and SURFSENSE_DOMAIN must stay unset" >&2; exit 64; fi; if [ "$(id -u)" != 0 ]; then echo "SurfSense refused to start: RAILWAY_RUN_UID must stay 0, so the start command can install its Caddyfile and hand the volume to UID 1000" >&2; exit 64; fi; mkdir -p /app/caddy-railway; cp /app/caddy/routes.caddy /app/caddy/access.caddy /app/caddy/spa.caddy /app/caddy-railway/; printf %s "IyBUaGUgdGVtcGxhdGUncyByZXBsYWNlbWVudCBmb3IgU3VyZlNlbnNlJ3Mgb3duIHBsYWluLUhUVFAgQ2FkZHlmaWxlIChkb2NrZXIvc3VyZnNlbnNlL2NhZGR5L0NhZGR5ZmlsZSkuCiMgVGhlIHN0YXJ0IGNvbW1hbmQgd3JpdGVzIGl0IGJlc2lkZSBjb3BpZXMgb2YgdXBzdHJlYW0ncyByb3V0ZXMuY2FkZHksIGFjY2Vzcy5jYWRkeSBhbmQgc3BhLmNhZGR5LCBhbmQKIyBwb2ludHMgU1VSRlNFTlNFX0xPQ0FMX0NBRERZRklMRSBhdCBpdCwgc28gU3VyZlNlbnNlJ3Mgcm91dGVzIGFuZCBzaWduLWluIHN0YXkgZXhhY3RseSB1cHN0cmVhbSdzLgojCiMgVHdvIGFkZGl0aW9uczoKIwojIDEuIFJlZnVzZSBhIHJlcXVlc3Qgd2hvc2UgZGVjb2RlZCBwYXRoIGhvbGRzICUsID8sICMsIGEgYmFja3NsYXNoIG9yIGEgY29udHJvbCBjaGFyYWN0ZXIsIG9yIGVuZHMgaW4gYQojICAgIHNwYWNlLiBTdXJmU2Vuc2UgMi4zLjEncyBhY2Nlc3MgY2hlY2sgZGVjb2RlcyB0aGUgcmVxdWVzdCBwYXRoIG9uY2UgYW5kIHBhcnNlcyBpdCBhcyBhIFVSTC4gQSBVUkwKIyAgICBwYXJzZXIgZW5kcyB0aGUgcGF0aCBhdCA/IG9yICMsIHJlYWRzIGEgc3RpbGwtZW5jb2RlZCAlMmUlMmUgYXMgIi4uIiwgdHVybnMgXCBpbnRvIC8sIGRyb3BzIHRhYnMgYW5kCiMgICAgbmV3bGluZXMsIGFuZCBzdHJpcHMgdHJhaWxpbmcgc3BhY2VzLiBDYWRkeSByb3V0ZXMgb24gdGhlIGRlY29kZWQgcGF0aCBhbmQgZG9lcyBub25lIG9mIHRoYXQuIFNvCiMgICAgIi9hcGkvaGVhbHRoJTIzLy4uL3dvcmtzcGFjZXMiIGFuZCAiL2FwaS9sbG0vbW9kZWxzL3gvJTI1MmUlMjUyZS8lMjUyZSUyNTJlLyUyNTJlJTI1MmUvaGVhbHRoIiByZWFkIGFzCiMgICAgdGhlIHB1YmxpYyAvYXBpL2hlYWx0aCB0byB0aGUgYWNjZXNzIGNoZWNrIHdoaWxlIENhZGR5IHNlbnQgdGhlbSBpbnRvIHRoZSBBUEksIHdoaWNoIGFuc3dlcmVkIHdpdGhvdXQKIyAgICBhIHNlc3Npb24uIFdpdGhvdXQgdGhlc2UgY2hhcmFjdGVycyB0aGUgdHdvIHJlYWQgdGhlIHBhdGggdGhlIHNhbWUgd2F5LiBUaGUgb25lIGxlZ2l0aW1hdGUgY2FzdWFsdHk6CiMgICAgYSBsb2NhbCBtb2RlbCB3aG9zZSBmaWxlIG5hbWUgY29udGFpbnMgJSBjYW5ub3QgYmUgb3BlbmVkIG9yIGRlbGV0ZWQgZnJvbSB0aGUgYXBwIChyZW5hbWUgdGhlIGZpbGUpLgojCiMgMi4gQmVoaW5kIFJhaWx3YXkncyBlZGdlIChwZWVycyBpbiAxMDAuNjQuMC4wLzEwKSwga2VlcCB0aGUgZWRnZSdzIFgtRm9yd2FyZGVkLVByb3RvIChodHRwcyksIHNvIHRoZQojICAgIHNlc3Npb24gY29va2llIGlzIFNlY3VyZSBhbmQgT0F1dGggY2FsbGJhY2tzIHVzZSBodHRwcywgYW5kIGdpdmUgU3VyZlNlbnNlIHRoZSByZWFsIGNsaWVudCBhZGRyZXNzLgojICAgIFJhaWx3YXkncyBlZGdlIGRpc2NhcmRzIHdoYXQgdGhlIGNsaWVudCBzZW50IGFuZCB3cml0ZXMgWC1SZWFsLUlQOiA8Y2xpZW50PiBhbmQgWC1Gb3J3YXJkZWQtRm9yOgojICAgIDxjbGllbnQ+LCA8dGhlIGVkZ2UncyBvd24gcHVibGljIGFkZHJlc3MsIHdoaWNoIHZhcmllcyBieSBlZGdlIG5vZGU+LiBTdXJmU2Vuc2UncyBhY2Nlc3Mgc2VydmljZSBrZXlzCiMgICAgaXRzIHBhc3N3b3JkLWd1ZXNzIGxpbWl0IG9uIHRoZSBmaXJzdCBYLUZvcndhcmRlZC1Gb3IgZW50cnksIHNvIFgtRm9yd2FyZGVkLUZvciBpcyByZXBsYWNlZCB3aXRoIHRoZQojICAgIGNsaWVudF9pcCBDYWRkeSByZWFkcyBmcm9tIFgtUmVhbC1JUCwgYW5kIFgtRm9yd2FyZGVkLUhvc3Qgd2l0aCB0aGUgSG9zdCBSYWlsd2F5IHJvdXRlZCBvbi4gQW55IG90aGVyCiMgICAgcGVlciAobG9jYWwgRG9ja2VyLCBSYWlsd2F5J3MgcHJpdmF0ZSBuZXR3b3JrKSBnZXRzIHVwc3RyZWFtJ3MgYmVoYXZpb3VyIHVuY2hhbmdlZC4KewoJYWRtaW4gb2ZmCglhdXRvX2h0dHBzIG9mZgoJc2VydmVycyB7CgkJdHJ1c3RlZF9wcm94aWVzIHN0YXRpYyAxMDAuNjQuMC4wLzEwCgkJY2xpZW50X2lwX2hlYWRlcnMgWC1SZWFsLUlQCgl9Cn0KCjo4MCB7Cglyb3V0ZSB7CgkJIyBUaGUgZGVjb2RlZCBidXQgdW5jbGVhbmVkIHBhdGg6IHBhdGhfcmVnZXhwIHdvdWxkIG1hdGNoIGFmdGVyIGRvdCBzZWdtZW50cyBhcmUgcmVtb3ZlZCwgYnkgd2hpY2gKCQkjIHBvaW50ICJoZWFsdGgjLy4uIiBpcyBhbHJlYWR5IGdvbmUuCgkJQGFtYmlndW91cyB2YXJzX3JlZ2V4cCB7aHR0cC5yZXF1ZXN0LnVyaS5wYXRofSBgWyU/I1x4MDAtXHgxZlx4NWNceDdmXXwgJGAKCQlyZXNwb25kIEBhbWJpZ3VvdXMgNDAwIHsKCQkJY2xvc2UKCQl9CgkJcmVxdWVzdF9oZWFkZXIgWC1Gb3J3YXJkZWQtRm9yIHtjbGllbnRfaXB9CgkJcmVxdWVzdF9oZWFkZXIgWC1Gb3J3YXJkZWQtSG9zdCB7aG9zdH0KCQlpbXBvcnQgcm91dGVzLmNhZGR5Cgl9Cn0K" | base64 -d >/app/caddy-railway/Caddyfile; export SURFSENSE_LOCAL_CADDYFILE=/app/caddy-railway/Caddyfile; if [ -z "${SURFSENSE_LOCAL_DOMAIN:-}" ] && [ -n "${RAILWAY_PUBLIC_DOMAIN:-}" ]; then export SURFSENSE_LOCAL_DOMAIN="$RAILWAY_PUBLIC_DOMAIN"; fi; [ "$(stat -c %u:%g /data)" = 1000:1000 ] || chown 1000:1000 /data; exec setpriv --reuid=1000 --regid=1000 --clear-groups tini -g -- node /app/surfsense_local/headless/main.ts'`
- **Health check:** /api/health
- **Public domain:** Yes

## Documentation

# Deploy and Host SurfSense Research on Railway

[SurfSense](https://www.surfsense.com) is an open-source, self-hosted alternative to NotebookLM. You upload your documents, SurfSense indexes them, and its chat answers questions from them with citations. It can also turn them into podcasts and reports. This template runs the official SurfSense 2.3.1 image behind a generated password, with all its data on one volume. Source: [github.com/MODSetter/SurfSense](https://github.com/MODSetter/SurfSense).

## About Hosting SurfSense Research

SurfSense 2.x ships as one container. Inside it are:

- the Python API;
- background workers for document ingest, studio jobs and plugins;
- local model servers (llama.cpp, audio.cpp, sd.cpp);
- Caddy, which serves the web app and checks a session on every request.

This template runs that image, pinned by digest, as one Railway service with a 5 GB volume at `/data`. The volume holds SQLite, uploaded files, the search index and models. The image bundles the BGE Small embedder and Docling parser models, so indexing and search work from the first start.

The template generates a 32-character `SURFSENSE_PASSWORD`. The service refuses to start without a password of 16 or more characters and refuses to turn sign-in off. It runs SurfSense as a non-root user. It also refuses malformed request paths that let anonymous requests past SurfSense 2.3.1's sign-in check on the stock image. Chat needs a model: connect OpenAI, Anthropic, Gemini, OpenRouter or any OpenAI-compatible endpoint after you sign in, or download a local model.

## Common Use Cases

- A private research notebook: ask questions across your PDFs, Office files, notes and saved web pages, with cited answers.
- Team or project knowledge you can query from any browser, without running a desktop app.
- Podcasts, summaries and reports generated from your own sources.
- A NotebookLM-style workflow that keeps the documents on infrastructure you control.

## Dependencies for SurfSense Research Hosting

- A model provider for chat and studio outputs: an API key from OpenAI, Anthropic, Google, OpenRouter or another OpenAI-compatible service. Local models run on CPU and need much more memory.

### Deployment Dependencies

- SurfSense website: https://www.surfsense.com
- SurfSense source and documentation: https://github.com/MODSetter/SurfSense
- Container image: `ghcr.io/modsetter/surfsense:2.3.1` (linux/amd64)

### Implementation Details

After the deploy, open the SurfSense service's Variables tab, copy `SURFSENSE_PASSWORD`, open the public domain and sign in. SurfSense applies the variable at every start. To change the password, set a new value of 16 or more characters and redeploy. Each redeploy signs browsers out.

On Railway the service idled at about 0.56 GB of memory and stayed under 0.8 GB while indexing documents and answering questions with a remote model. Local models need several GB more. Grow the volume before downloading them.

## Why Deploy SurfSense Research 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 Research 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.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [Weaviate](https://railway.com/deploy/weaviate-1) — Vector database with hybrid search and an API key-protected API
- [Möbius Personal AI OS](https://railway.com/deploy/mobius-v01-personal-ai-os) — Self-hosted AI agent that builds and runs apps for you, with memory.

Open this page in a browser: https://railway.com/deploy/surfsense-research
