# Installing Synapse on a Linux server Synapse is a single Node.js process: the API serves the built web app itself and applies database migrations automatically at boot. A minimal install is one service plus a reverse proxy for TLS. ## 1. Prerequisites - Node.js ≥ 20.19 (22 LTS recommended) and pnpm ≥ 9 (`corepack enable` ships pnpm with Node). - Build tools for the bundled SQLite driver: `apt install build-essential python3`. - Optional, for document conversion (uploads beyond PDF): - `pandoc` + `typst` for markup formats (md, html, epub, tex, ...): download the static binaries from their GitHub releases and point `PANDOC_PATH` at pandoc (typst just needs to be on `PATH`). - LibreOffice for office formats (docx, pptx, xlsx, ...): `apt install --no-install-recommends libreoffice-writer libreoffice-impress libreoffice-calc` and set `SOFFICE_PATH` if `soffice` is not on `PATH`. Without it, office uploads are rejected with an install hint, and everything else works. - Optional, for AI features: an API key, configurable later from Settings. The default setup works with OpenAI's free usage tier; see [AI.md](ai.md). ## 2. Docker (the short way) The repository ships a Dockerfile and a compose example. With Docker installed, this is the whole install: ```bash git clone https://tangled.org/denishovart.com/synapse synapse && cd synapse # set SESSION_SECRET in docker-compose.yml first (any long random string) docker compose up -d --build ``` The app answers on `http://localhost:3000`; database and uploads live in named volumes. Seed the example courses once, if you want them: ```bash docker compose exec synapse node dist/scripts/seed.js ``` Document conversion tools are not baked into the default image to keep it small: it accepts PDF uploads only. The `plus` build target adds LibreOffice for office formats (docx, pptx, xlsx and the legacy binary ones) and pandoc with weasyprint for markup formats (md, html, epub, tex): ```bash docker build --target plus -t synapse:plus . ``` Published images follow the same split: the `latest` tag is the small image, `latest-plus` includes the conversion tools. The image is roughly 1 GB larger with LibreOffice in it, which is the whole reason for the two variants. To get the conversion tools through compose, point the service at the same target: ```yaml services: synapse: build: context: . target: plus ``` Uploads of formats the running image cannot convert are rejected with a message naming the missing tool, so switching variants later is safe: nothing is stored half-converted. Put a TLS reverse proxy in front before exposing it beyond localhost, then continue at step 5 for accounts. The rest of this page is the manual install, without Docker. ## 2b. Build ```bash git clone https://tangled.org/denishovart.com/synapse synapse && cd synapse pnpm install pnpm build # builds the API (apps/api/dist) and the web app (apps/web/dist) ``` ## 3. Configure ```bash cp apps/api/.env.example apps/api/.env ``` The minimum for a server install: ```ini # apps/api/.env PORT=3000 HOST=127.0.0.1 # keep loopback; the reverse proxy is the front door SESSION_SECRET= # node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" DB_DIALECT=sqlite # zero-config; or postgres + DATABASE_URL ``` Everything else (`AUTH_*`, conversion binaries, upload size, AI) is documented in `.env.example` and [auth.md](auth.md). The SQLite database lives in `apps/api/data/` by default. Back up both `apps/api/data/` and `apps/api/uploads/` (or wherever `UPLOADS_DIR` points, if you moved the content store off the default path): the uploads tree is the content store holding documents and sync payloads, the database holds the metadata that points into it. Back them up in order, database first: copy the database (`sqlite3 data/synapse.db ".backup data/backup.db"` for a consistent copy while running, or dump your Postgres), then copy `uploads/`. That order can only leave the uploads tree ahead of the database, which is harmless (an extra file no row points at yet); the reverse could record a blob whose bytes were not copied. Those two folders restore the server: the accounts, the stored files and the sync log devices pull from. They do not cover a device whose changes never reached the server, because the workspace itself lives on the devices. For that, export the workspace from `Settings > Backup & sync` on the device. SQLite is the default because a single household server does not need more. If you prefer Postgres, set `DB_DIALECT=postgres` and `DATABASE_URL`; the compose file ships a commented database service to uncomment. ## 4. Run as a service ```ini # /etc/systemd/system/synapse.service [Unit] Description=Synapse revision app After=network.target [Service] User=synapse WorkingDirectory=/opt/synapse/apps/api ExecStart=/usr/bin/node dist/main.js Restart=on-failure Environment=NODE_ENV=production [Install] WantedBy=multi-user.target ``` ```bash useradd --system --home /opt/synapse synapse # dedicated user, no login systemctl enable --now synapse ``` Migrations run automatically at startup; there is no separate migrate step. Upgrades are `git pull && pnpm install && pnpm build && systemctl restart synapse`. ## 5. TLS in front Keep the app on loopback and terminate TLS in a reverse proxy. Caddy is the shortest path (automatic certificates): ``` # /etc/caddy/Caddyfile synapse.example.org { reverse_proxy 127.0.0.1:3000 } ``` HTTPS is not optional: the session cookie is `Secure` in production, and the PWA install requires a secure context. For a private deployment without a public domain, Tailscale (`tailscale cert`) gives you HTTPS with zero exposure. ## 6. First run Open the URL: Synapse shows a one-time "create the first account" screen - that account is the admin. From Settings → Users the admin creates further accounts (or set `AUTH_ALLOW_SIGNUP=true` for open self-registration). Each user's data is strictly isolated. On a phone, open the same URL and "Add to Home Screen", which installs it as a PWA. ## The web client, with no server at all The app also builds as a plain static site: the same local-first client the shells embed, running entirely in the browser. There is no account and no backend; the workspace lives in the browser's storage, and a server can still be connected later from Settings > Backup & sync. The build ships a small example workspace (the MIT OpenCourseWare courses), so it doubles as an online demo. ```bash pnpm --filter @synapse/web build:web-client # result: apps/web/dist-web-client ``` Deploy that folder to any static host. Cloudflare Pages and Netlify have free tiers that fit comfortably (the `_redirects` file included in the build gives deep links the SPA fallback both hosts understand). For GitHub Pages, copy `index.html` to `404.html` instead. Two limits compared to the shells: converting non-PDF uploads needs a server or a desktop install, and device-to-device LAN sync is a shell feature. To let a hosted web client connect to your server, add its origin to the server's `CORS_ORIGINS`. ## Browser support Synapse targets evergreen browsers (roughly 2023 and newer: Chrome 111+, Firefox 121+, Safari 16.2+). Older browsers degrade progressively: custom select styling, tinted quiz feedback and some empty-state centering fall back to plainer looks. The app works over plain http on a trusted LAN, but PWA install needs HTTPS. See [auth.md](auth.md) for accounts, passwords, recovery, and SSO.