Self-hosting guide

Posy runs as one Node app with a SQLite (or Turso) database and a place for uploads. Everything is unlocked on a self-hosted instance. The first account you create owns it, and / is that account’s page. If you would rather not run a server, posy.page hosts the same app. Pages move both ways with Settings, Download page.json and Import page.json.

Docker

docker build -t posy .
docker run -d --name posy -p 3000:3000 -v posy-data:/data \
  -e NEXT_PUBLIC_SITE_URL=https://links.example.com \
  -e BETTER_AUTH_URL=https://links.example.com \
  -e BETTER_AUTH_SECRET=$(openssl rand -base64 32) \
  --restart unless-stopped posy

Use http://localhost:3000 for both URLs while trying it out. Open the URL and sign up.

Docker Compose

Edit docker-compose.yml: set the two URLs and a long random BETTER_AUTH_SECRET (openssl rand -base64 32), then:

docker compose up -d

Vercel (Turso + Blob)

Vercel has no persistent disk, so use a hosted database and file store.

Create a database at turso.tech. Note its URL (libsql://...) and create an auth token.
Press the Deploy button in the README, or import the repo in Vercel.
In the project, add a Blob store (Storage tab, Blob). That creates BLOB_READ_WRITE_TOKEN.
Set the environment variables below: DATABASE_URL, DATABASE_AUTH_TOKEN, BETTER_AUTH_SECRET, NEXT_PUBLIC_SITE_URL and BETTER_AUTH_URL (both your final URL, for example https://links.example.com).
Deploy, open the URL and sign up. Migrations run on start.

Any Node host

npm ci
npm run build
NEXT_PUBLIC_SITE_URL=https://links.example.com BETTER_AUTH_URL=https://links.example.com \
BETTER_AUTH_SECRET=... POSY_DATA_DIR=/var/lib/posy npm start

Node 20.9 or newer. Set NEXT_PUBLIC_SITE_URL before npm run build, since it is baked into the build.

Environment

Posy checks its environment when the server starts. In production it refuses to boot, and tells you what to fix, if a required variable is missing, if BETTER_AUTH_SECRET is shorter than 32 characters, the built-in development secret or the placeholder from docker-compose.yml (change-me-to-a-long-random-string), or if the two URLs disagree. In development everything has a default. .env.example has every variable with comments.

Variable	Default	Notes
`NEXT_PUBLIC_SITE_URL`	`http://localhost:3000`	Required in production. Public URL, used for share links and images. Set before `npm run build`.
`BETTER_AUTH_URL`		Required in production. Same scheme and host as `NEXT_PUBLIC_SITE_URL`.
`BETTER_AUTH_SECRET`		Required in production. 32+ characters: `openssl rand -base64 32`.
`POSY_SIGNUP`	`first-user`	`open`, `closed` or `first-user`.
`POSY_DATA_DIR`	`.data` (`/data` in Docker)	SQLite file and uploads.
`DATABASE_URL`	local file	Turso / libSQL URL. Required on Vercel.
`DATABASE_AUTH_TOKEN`		Required with a remote `DATABASE_URL`.
`BLOB_READ_WRITE_TOKEN`		Vercel Blob for uploads (needed on Vercel).
`GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`		GitHub sign-in (set both).
`GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`		Google sign-in (set both).
`GITHUB_TOKEN`		Higher API limit for repo tiles.
`POSY_TELEMETRY`	on in production	Set `0` to turn off anonymous usage stats. `DO_NOT_TRACK=1` works too. See telemetry.
`POSY_TELEMETRY_KEY`, `POSY_TELEMETRY_HOST`	Posy’s PostHog	Only for forks that want their own PostHog project.
`POSY_URL`, `POSY_API_KEY`		Used by `npm run posy` and agents, not by the server.

Your own domain

There is nothing to enable in Posy. Point your domain’s DNS at your server (or at Vercel, after adding the domain to the project), make sure it serves HTTPS, and set NEXT_PUBLIC_SITE_URL and BETTER_AUTH_URL to that address. Your page is the home page of the domain. On a plain server, put a reverse proxy in front for HTTPS. With Caddy that is two lines:

links.example.com {
  reverse_proxy localhost:3000
}

Backups

Everything lives in the data directory (/data in Docker): posy.db and your uploads. Copy that folder and you have a backup.

docker run --rm -v posy-data:/data -v "$PWD":/backup alpine tar czf /backup/posy-data.tgz -C /data .

On Turso, use its own backups, and your uploads are in Vercel Blob. A lighter backup of just your page: Settings, Download page.json (or npm run posy -- export page.json).

Upgrading

git pull
docker compose build && docker compose up -d

Migrations run when the app starts. Back up the data directory first. On Vercel, pull the new code and redeploy.

​Docker

​Docker Compose

​Vercel (Turso + Blob)

​Any Node host

​Environment

​Your own domain

​Backups

​Upgrading