notekpr

Self-host

Run it yourself

notekpr is one small server: a Rust binary, a SQLite file and the web app. Here is how to try it, run it for real, and keep it safe.

This is the short version; every setting and option is in the docs: running a server.

Rather not run a server? Hosted plans are coming: the same app and the same encryption, on our servers, or run by us on yours.

Try it first

Development mode needs no sign-in provider. Sign in as any name, then open a second browser tab and sign in as someone else to try sharing and live editing between two people.

Or run task demo for a server with users, shared vaults and linked notes already in it. The same demo is online too, nothing to install: demo.notekpr.md.

Never expose development mode to a network: anyone can sign in as anyone.

# with Docker
$ docker compose -f docker-compose.dev.yml up --build

# or from source (Rust, wasm32 target, wasm-bindgen)
$ task setup
$ task dev

# then open http://localhost:8080

Run it for real

You need a machine with Docker (or a Kubernetes cluster), a domain name pointing at it, a reverse proxy for HTTPS, and an OpenID Connect provider such as Authelia, Keycloak, Authentik or Google. The server comes as a container image for amd64 and arm64, ghcr.io/coolapso/notekpr, with every release.

notekpr serves plain HTTP and leaves certificates and HTTPS to the proxy you already use. If you don't have one, the docs have examples for Caddy (automatic HTTPS in one command), Traefik and nginx.

Register notekpr with your provider, with the redirect address https://your.domain/api/v1/auth/oidc/callback, and hand the details to Compose through the environment, from wherever you keep your secrets.

The first person to sign in becomes the administrator.

$ git clone https://github.com/coolapso/notekpr
$ cd notekpr
$ export NOTEKPR_PUBLIC_URL=https://notes.example.com
$ export NOTEKPR_OIDC_ISSUER=https://auth.example.com
$ export NOTEKPR_OIDC_CLIENT_ID=notekpr
$ export NOTEKPR_OIDC_CLIENT_SECRET=…  # from your secret store
$ docker compose up -d
# notekpr on 127.0.0.1:8080: point your proxy at it

Back it up

Encrypted notes, their history and keys wrapped for members live in one SQLite database; a backup is a consistent copy of that file, made while the server runs. Attachments are files in a folder next to it, or in S3-compatible storage, never changed once written: copy them after the database. Backups are encrypted data too; they need people's own keys to read.

$ docker compose exec notekpr \
    notekpr-server backup --out-dir /data/backups --keep 14

The command-line client

Install the notekpr command-line client and run notekpr setup once per computer: it signs you in, keeps your vaults as a folder of Markdown files that you edit with any editor, and can keep that folder in sync in the background.

Packages for Linux, amd64 and arm64: notekpr-cli-bin in the AUR, COPR for Fedora, and a .deb, an .rpm and a .tar.gz with each release. Elsewhere, build it from source.

Installing it · Use your own editor · All CLI commands

# Fedora
$ sudo dnf copr enable coolapso/notekpr
$ sudo dnf install notekpr-cli

# Debian, Ubuntu: the .deb of a release
$ sudo apt install ./notekpr-cli_<version>_amd64.deb

$ notekpr setup

Going further

  • KubernetesManifests for a single replica with a persistent volume and a backup CronJob.
  • Other reverse proxiesnginx and Traefik work too; the server needs WebSockets and the forwarded client address.
  • MonitoringPrometheus metrics, health and readiness endpoints.
  • UpgradesDatabase migrations run on start, after an automatic backup. The server tells connected apps it's restarting; they keep working and are back about a second after it is.
  • Admin pageAccounts, who is an administrator, disabling an account, and server statistics. Administrators can't read anyone's notes or vault names.
  • Limits and read-only modeChange them while the server runs: how many accounts, agents and vaults, how many vaults and agents each person may have (and one person more), how much the whole instance may store (the room a family or a team shares), and a read-only mode. People's edits wait on their devices while it is on.
  • Admin clientsFor scripts and services such as a billing system: each gets its own scopes and tokens for the admin API, never reaches a vault, and can be set up from the server's command line or your deployment's configuration. An instance can leave everything to them and have no administrators among its people.
  • Where files goAttachments in a folder (the default), in S3 or anything compatible — several servers can share a bucket, each under its own prefix — or inside the database, for one-file backups. Existing ones move by themselves.
  • Size limitsSet how large a single change, a snapshot and an attachment may be.
  • How big a server?A load test you can watch, task load: a crowd of simulated people with real encryption against the server image with CPU and memory limits.

Configuration, identity providers, proxies, backups and upgrades are covered in the docs: running a server.