SafeSprint docs

SafeSprint is a self-hosted Kanban board. Teams get organizations, shared and private boards, cards with all the usual details, and live updates while several people work on the same board.

The name says what it is for. Safe: it runs on your server and keeps everything in your own Postgres database, with no hosted service behind it. Sprint: it is shaped around project sprints, with a backlog, work in progress limits, estimates and due dates.

It's a Next.js app with PostgreSQL, released under the MIT license. The source is on GitHub.

To try it on your own machine you need Docker with Compose v2.

git clone https://github.com/JayavandePol/SafeSprint.git
cd SafeSprint
AUTH_SECRET=$(openssl rand -base64 32) POSTGRES_PASSWORD=$(openssl rand -hex 24) docker compose up -d --build

Open http://localhost:3000 and create an account. Without an email server, verification links are printed to the log: docker compose logs app.

A SafeSprint install is two containers: the app and PostgreSQL. Anything that runs Docker Compose can host it. Pick the guide for your setup below, then read HTTPS and proxies.

git clone https://github.com/JayavandePol/SafeSprint.git /opt/safesprint
cd /opt/safesprint
cat > .env <<EOF
APP_URL=https://boards.example.com
AUTH_SECRET=$(openssl rand -base64 32)
POSTGRES_PASSWORD=$(openssl rand -hex 24)
CRON_SECRET=$(openssl rand -hex 24)
APP_BIND=127.0.0.1:3000
TRUSTED_PROXY_HOPS=1
EOF
chmod 600 .env
docker compose up -d --build

APP_URL=https://boards.example.com
AUTH_SECRET=...            # openssl rand -base64 32
POSTGRES_PASSWORD=...      # openssl rand -hex 24
CRON_SECRET=...            # openssl rand -hex 24
APP_BIND=127.0.0.1:3001
TRUSTED_PROXY_HOPS=1

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
    client_max_body_size 12m;
}

boards.example.com {
    reverse_proxy 127.0.0.1:3000 {
        flush_interval -1
    }
}

All settings are environment variables. With Docker Compose they go in .env; the compose file passes them to the app. .env.example in the repository lists every one with a comment.

Email is used for verification, password resets, invitations, notifications and the digest. Without it, messages are written to the app log instead, and people can't verify their address or reset a password on their own.

Fill in the fields your provider gives you:

SMTP_HOST=smtp.example.com
SMTP_PORT=465
SMTP_USER=noreply@example.com
SMTP_PASSWORD=...
SMTP_SECURE=true
MAIL_FROM="SafeSprint <noreply@example.com>"

Port 465 uses TLS from the first byte (SMTP_SECURE=true). Port 587 starts plain and upgrades with STARTTLS (SMTP_SECURE=false). Leave SMTP_SECURE empty and it is worked out from the port. If you'd rather use one line, SMTP_URL=smtps://user:pass@smtp.example.com:465 works too, but special characters in the password then need URL encoding.

The domain in MAIL_FROM has to be verified with your provider (SPF and DKIM), or your mail will land in spam.

Attachments can be up to 10 MB each and 250 MB per board. By default they are stored in Postgres, so there is nothing extra to run or back up. Downloads always go through the app, which checks that the person can see the board.

To keep files in object storage instead, set the S3_* variables. This works with AWS S3, Cloudflare R2, Backblaze B2, or a self-hosted server such as Garage or SeaweedFS.

S3_BUCKET=safesprint
S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com   # leave out for AWS
S3_REGION=auto
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...

The key needs GetObject, PutObject and DeleteObject on the bucket, plus ListBucket if you create the bucket yourself. Files already stored in Postgres keep working after you switch.

You can add Umami, Plausible or Google Analytics to the public pages: the landing page and these docs. Analytics never load inside the app, so board names and card links don't end up in a third-party dashboard.

# Umami Cloud
UMAMI_SCRIPT_URL=https://cloud.umami.is/script.js
UMAMI_WEBSITE_ID=00000000-0000-0000-0000-000000000000

# or Plausible
PLAUSIBLE_DOMAIN=boards.example.com

# or Google Analytics 4
GA_MEASUREMENT_ID=G-XXXXXXXXXX

Set one of them. If more than one is set, Umami is used first, then Plausible. Malformed values switch analytics off instead of breaking the page, and the Content Security Policy only opens up for the hosts you configure.

# Self-hosted Umami
UMAMI_SCRIPT_URL=https://umami.example.com/script.js
UMAMI_WEBSITE_ID=00000000-0000-0000-0000-000000000000
UMAMI_HOST_URL=https://umami.example.com      # optional, where data is sent
UMAMI_DOMAINS=boards.example.com              # optional, only track this hostname

# Self-hosted Plausible (Community Edition)
PLAUSIBLE_DOMAIN=boards.example.com
PLAUSIBLE_SCRIPT_URL=https://plausible.example.com/js/script.js
PLAUSIBLE_API_URL=https://plausible.example.com/api/event   # optional

PLAUSIBLE_SCRIPT_URL=/stats/js/script.js
PLAUSIBLE_API_URL=/stats/api/event

The buttons only show up once the credentials are set.

• Google: Google Cloud Console → APIs & Services → Credentials → OAuth client ID (Web). Callback URL https://boards.example.com/api/auth/callback/google.
• GitHub: Settings → Developer settings → OAuth Apps. Callback URL https://boards.example.com/api/auth/callback/github.

AUTH_GOOGLE_ID=...
AUTH_GOOGLE_SECRET=...
AUTH_GITHUB_ID=...
AUTH_GITHUB_SECRET=...

People who opt in get one email a day with unread notifications and cards that are due soon. Something has to call the digest endpoint on a schedule, for example cron:

0 7 * * * curl -fsS -H "Authorization: Bearer YOUR_CRON_SECRET" https://boards.example.com/api/cron/digest > /dev/null

Calling it more often is harmless. Nobody gets more than one digest in about 20 hours.

cd /opt/safesprint
git pull
docker compose up -d --build

Migrations run when the new container starts. Take a backup first. On Dokploy, press Deploy again or turn on auto-deploy for the branch.

With the default setup, everything, attachments included, is in one database:

docker compose exec -T db pg_dump -U safesprint -Fc safesprint > safesprint-$(date +%F).dump

Run that nightly and copy the files off the server. To restore onto a fresh install with the same .env:

docker compose up -d db
docker compose exec -T db pg_restore -U safesprint -d safesprint --clean --if-exists < safesprint-YYYY-MM-DD.dump
docker compose up -d

If you use S3 storage, back up the bucket as well.

• Every action checks, on the server, that you may see and change the board it touches. Hidden boards return 404.
• Passwords are hashed with bcrypt, checked against a list of common passwords and, unless turned off, against Have I Been Pwned using only a hash prefix.
• Two-factor secrets are encrypted at rest, and recovery codes are stored hashed.
• Sessions are tracked on the server, so signing out or changing your password takes effect right away on every device.
• Sign-in, sign-up, password resets, invites, uploads and imports are rate limited. Invites can only be sent from a verified email address.
• On a private server, set REGISTRATION=invite so only people you invite (or on your REGISTRATION_DOMAINS) can create an account.
• A strict Content Security Policy with a per-request nonce, HSTS in production, and no framing.
• Attachments are served through the app with nosniff; only common image types display inline.

Found a problem? Please report it privately to the maintainer through GitHub's security page rather than in a public issue.

The deploy says “Set AUTH_SECRET”

The variables never reached Compose. Put them in .env next to docker-compose.yml, or in your panel's environment settings, and deploy again.

“port is already allocated” on Dokploy

Dokploy's own dashboard uses port 3000. Set APP_BIND=127.0.0.1:3001.

Email links point to localhost

Set APP_URL to the public address and restart.

Changes from others only appear after a reload

Your proxy is buffering the event stream. Turn buffering off for /api/boards/.

Everyone gets rate limited at once

You're behind a proxy with TRUSTED_PROXY_HOPS=0, so every visitor looks like the proxy. Set it to the number of proxies.

Sign-in fails with UntrustedHost

Keep AUTH_TRUST_HOST=true. The Compose file already sets it.

Uploads fail

Check docker compose logs app for [upload] lines. With S3 configured it is usually a wrong key or endpoint.

GET /api/health answers {"status":"ok"} when the app can reach its database.

To run SafeSprint from source you need Node.js 22 and PostgreSQL 14 or newer.

npm install
cp .env.example .env     # set DATABASE_URL, AUTH_SECRET and APP_URL
npm run db:migrate
npm run db:seed          # optional: demo@example.com / Demo-Password-2024
npm run dev

npm run lint, npm run typecheck and npm test should pass before you open a pull request. Issues and pull requests are welcome on GitHub.