Synapse is a study workspace. Organize courses read and annotate the material, train with generated exercises and watch your progress forked from denishovart.com/synapse
synapse docs setup.md
7.6 kB · 204 lines
Markdown

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.

2. Docker (the short way) #

The repository ships a Dockerfile and a compose example. With Docker installed, this is the whole install:

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:

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):

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:

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 #

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 #

cp apps/api/.env.example apps/api/.env

The minimum for a server install:

# apps/api/.env
PORT=3000
HOST=127.0.0.1          # keep loopback; the reverse proxy is the front door
SESSION_SECRET=<paste>  # 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. 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 #

# /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
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.

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 for accounts, passwords, recovery, and SSO.