Papyr Write together in Markdown. The server can't read it. Try it GitHub

Configuration

Papyr reads its settings from three sources, each overriding the one before:

  1. appsettings.json beside the binary (published with it; in the image, /app/appsettings.json). It holds every setting with its default, so it is the place to look a setting up. An appsettings.json in the current directory is read after it.
  2. Environment variables, with __ for each :: Papyr__DataDirectory=/srv/papyr.
  3. The command line: --Papyr:DataDirectory=/srv/papyr.

An invalid value stops the start with a message that names the setting and what to set instead.

Six settings are optional and hold an empty string in the file, which means “not set”: Papyr:TrustedProxies, Papyr:Relay:AllowedOrigins, Papyr:Admin:Token, Papyr:Admin:TokenFile, Papyr:Backup:Directory and Papyr:Web:FrameAncestors. Every other setting needs a value; an empty one stops the start.

If you host the relay in your own app (hosting.md), it reads Papyr:DataDirectory, FlushIntervalSeconds, RoomExpiryDays, Relay:*, Blobs:*, Admin:* and Backup:*. The rest (TrustedProxies, HttpConnections, Tls:*, Web:*, --webroot) belongs to Papyr.Server.

The server

Setting Default What it does
Papyr:DataDirectory data under the current directory; /data in the image Where the rooms are kept, in rooms/. Created at the start; one that cannot be created stops the start.
Papyr:FlushIntervalSeconds 5 (1 to 3600) How often update logs are flushed to disk. A crash of the machine can lose the last interval’s updates; the clients send them again.
Papyr:RoomExpiryDays 0 (0 to 36500) Remove a stored room nobody wrote to for this many days (operations.md, “Expiry”). 0 keeps every room nobody writes to. A room made with an expiry of its own is removed at it whatever this says.
Papyr:TrustedProxies empty Comma-separated addresses (10.89.0.1, ::1) and CIDR networks (10.0.0.0/8, fd00::/8) of the proxies whose X-Forwarded-For names the client. Only the header’s last entry is used, and only from these peers. Empty: the connection’s own address. Refused at the start: an entry that is neither, a network of every address (0.0.0.0/0, ::/0) or one with bits beyond its prefix (10.0.0.1/8). See operations.md, “Behind a proxy”.
Papyr:Relay:AllowedOrigins empty Comma-separated origins of pages on other hosts that may open a relay WebSocket, written as a browser does: https://notes.example, https://notes.example:8443, app://obsidian.md, capacitor://localhost. A relay request whose Origin is neither the request’s own Host (same port) nor one of these gets 403; a request without Origin passes. The site’s own pages need no entry as long as the proxy passes the browser’s Host (self-hosting.md, “Behind a reverse proxy”; event 33 says when it does not). Compared whole, ignoring ASCII case: https://a.example does not admit http://a.example. Refused at the start: an entry with its scheme’s default port (https://a.example:443: browsers omit it), *, null, a path, a trailing /, a query, user information, a host with _ or outside ASCII (write an IDN as xn--).
Papyr:Web:FrameAncestors empty Comma-separated origins of sites that may show the start page (/) and the room page (/r) in a frame, in the form above. Sets Content-Security-Policy: frame-ancestors on those two pages; empty is 'none'. The admin page and HTML files at their own path (/room.html) stay 'none'. Refused at the start: an entry that is not an origin, an IPv6 address, or an http:// site other than localhost, *.localhost or 127.0.0.0/8 (a plain-HTTP frame is no secure context, so no room opens there). Read self-hosting.md, “Embedding”, first.
Papyr:Web:PlantUml false true shows a fenced block ```plantuml in the preview as a diagram. The preview then loads the PlantUML engine (about 1.4 MB, cached) from cdn.jsdelivr.net, at a pinned version and checked by hash, into a sandboxed frame that /plantuml serves; no PlantUML server is asked, and the CDN learns that an address loaded PlantUML. The sandbox keeps the engine from the room’s key, its text, storage and connection; the diagram sources it is sent are protected by the pinned, hash-checked release alone: a malicious release could send them away. Turn it on only if you trust that release. The room page’s frame and the sites in Papyr:Web:FrameAncestors may frame /plantuml; the file /plantuml/frame.html at its own path is a static file no site can frame. false has no /plantuml route (404), and the preview shows the code block. Refused at the start: a value that is not true or false.
Papyr:HttpConnections 256 (1 to 10^6) Connections each listening address holds before they become WebSockets (“Connections”).
ASPNETCORE_URLS, --urls http://localhost:5000 Where Kestrel listens. The image sets ASPNETCORE_HTTP_PORTS=8080 and exposes 8443 for TLS. Kestrel:Endpoints:* works too and replaces these addresses.
--webroot wwwroot under the current directory The pages and scripts. Everything in it is public, symbolic links included (also ones that point out of it). Paths with a segment starting with a dot are not served, except /.well-known/. A data directory or token file inside it, or a web root inside the data directory, stops the start.
Logging:LogLevel:<category> Default Information; Microsoft.AspNetCore Warning; Microsoft.AspNetCore.Server.Kestrel.Connections Error Request logs are off. Logging:LogLevel:Microsoft.AspNetCore.Hosting=Information turns them on; they hold each request’s path and query, and the admin API’s hold room ids, so keep such a log as private as the data directory.
ASPNETCORE_FORWARDEDHEADERS_ENABLED not set Must not be true: the start stops, because ASP.NET Core would then trust X-Forwarded-For from any client. Use Papyr:TrustedProxies.

Every room needs HTTPS, open rooms too: browsers give the encryption API only to HTTPS pages and localhost. Serve it from Papyr (“TLS”) or from a reverse proxy (self-hosting.md, “Behind a reverse proxy”).

Connections

Kestrel holds at most Papyr:HttpConnections connections on each address it listens on (localhost is two addresses, the TLS listener one more). One more is closed as it is accepted, before any TLS handshake, with no answer. A connection that becomes a relay WebSocket stops counting here and is bounded by Papyr:Relay:ServerConnections instead, so rooms never crowd out page loads. An idle connection is closed after 15 seconds (no setting).

A page load opens up to 6 connections and then one WebSocket; the 6 stay open for 15 seconds. The default of 256 serves about 40 page loads in those 15 seconds and holds at most 28 MiB per address (45 MiB more on the TLS listener, “Memory”). Behind a proxy, the proxy’s connections count, not the browsers’.

At the limit, new pages, reconnecting rooms and /health get no answer while every open WebSocket goes on. Papyr.Server health (the image’s HEALTHCHECK) still exits 0 for a connection that is closed unanswered, with a line on stderr: a container restarted during a connection flood would drop every room’s WebSocket. A monitor outside sees the refusal. Kestrel counts refused connections in kestrel.rejected_connections (telemetry.md).

TLS

Setting Default What it does
Papyr:Tls:CertificatePath empty PEM file with the certificate and its intermediates after it (certbot’s fullchain.pem).
Papyr:Tls:KeyPath empty PEM file with the unencrypted private key (certbot’s privkey.pem).
Papyr:Tls:Port 8443 (0 to 65535) The HTTPS port.
Papyr:Tls:Address empty The IP address to listen on with HTTPS (127.0.0.1, ::1, one of the machine’s). Empty: every address. A name or * stops the start.

With both paths set the server also listens with HTTPS on Papyr:Tls:Port. The HTTP listener stays as configured; nothing redirects between the two. One path without the other, or a pair that does not load (unreadable, not PEM, a key that is not the certificate’s), stops the start. The listener sends the certificate’s intermediates, speaks HTTP/1.1 only and serves one certificate for every name (no SNI).

The HTTPS listener serves everything the HTTP listener serves, /api included, on every address unless Papyr:Tls:Address names one. No proxy rule keeps /api inside then: the token alone guards it (admin-api.md, “Keep /api inside”).

Who reads the files. The server’s user must read both; in the image that is uid 1654. Certbot writes privkey.pem as root, mode 0600, under directories only root enters, so copy both files in a deploy hook: install -o 1654 -m 0600 "$RENEWED_LINEAGE"/fullchain.pem "$RENEWED_LINEAGE"/privkey.pem /srv/papyr-tls/. The image cannot bind a port below 1024; publish 8443 as 443 (-p 443:8443).

Renewal needs no restart. The server checks both files every 60 seconds (write time and length, through symbolic links) and loads the pair again when one changed. New connections get the new certificate within a minute; open ones keep theirs. A pair that does not load (half renewed, unreadable, malformed) keeps the certificate in use, with event 22 once per state of the files; a successful load logs event 21 with the expiry.

Validity. A new certificate that is expired or not yet valid is not loaded while the one in use is valid (event 22); one not yet valid loads by itself once it is. When both are outside their validity the new one loads. At the start the certificate loads whatever its validity, so a server whose certificate expired while it was down starts and renews in place, with event 29. Event 29 is also written when the certificate enters the last tenth of its validity (9 days of 90), when it expires, then once a day.

The admin API

The API (admin-api.md) is on when Token is set or the token file exists at the start. Papyr.Server token creates the file (admin-api.md, “Turning it on”). The server reads it at the start only.

Setting Default What it does
Papyr:Admin:Token empty The bearer token of /api: at least 32 characters, no blank or control character (openssl rand -base64 32).
Papyr:Admin:TokenFile empty: admin-token in the data directory A file holding the token (trailing line ends ignored): a Docker or Compose secret (/run/secrets/...) or the file the verb writes. Keep it out of rooms/, mode 0600.
State at the start Result
No token, no file No route under /api (404).
TokenFile names a file that does not exist API off, event 26.
Token set and a file at the default path The setting wins, the file is not read, event 27.
Both settings set; a file that cannot be read, is empty, or holds a token shorter than 32 characters or with a blank or control character The start stops.

Scheduled backups

Off unless IntervalHours is set. How it runs: operations.md, “Scheduled backups”.

Setting Default What it does
Papyr:Backup:IntervalHours 0 (0 to 720) Hours from the start of one backup to the next. 0: none.
Papyr:Backup:Directory empty Where the backups go; required with IntervalHours. Best on another volume than the data directory. Created (0700) when missing. Stops the start when it cannot be created or written, lies inside rooms/ or the web root, or another server holds its papyr-backup.lock.
Papyr:Backup:Keep 7 (1 to 100000) How many backups to keep; older ones of the server’s name pattern are removed after each backup.

The relay’s limits

Papyr:Relay:<Name>; as environment variables Papyr__Relay__<Name>. What each means on the wire: spec/relay-protocol.md, “Limits”.

Setting Default Range What it does
UpdateBytes 1048576 64 to 1 GiB Largest update, type byte included. Beyond: close 4001.
SnapshotBytes 8388608 64 to 1 GiB Largest snapshot message. Beyond: 4001.
StoredUpdates 2000 1 to 10^8 Stored updates per room after its snapshot. A snapshot is asked for past half; 4002 at the limit.
StoredBytes 4194304 UpdateBytes + 16 + 16384 to 1 TiB Memory those updates may hold (each body + 17, plus the unused ends of their 16 KiB blocks). Half and limit as above.
ConnectionsPerRoom 32 1 to 10^6 Connections per room. Beyond: 4000.
LoadedRooms 1000 1 to 10^8 Rooms in memory. Beyond: 4004.
QueuedBytes 16777216 2 x max(UpdateBytes + 16, 1032) + 16384 to 1 TiB What a connection may be behind on, counted as StoredBytes. Beyond, while a send to it is pending, it is aborted.
ServerConnections 256 1 to 10^6 Relay connections at once. Beyond: 503 before the upgrade.
ReceiveBytes 268435456 max(UpdateBytes, SnapshotBytes) to 1 TiB What all incoming messages hold together beyond their first 16 KiB each. Beyond: 1013. One source gets at most its share (below).
ConnectionsPerSource 32 1 to 10^6 Relay connections of one source. The one beyond is closed with 4005; further ones get 429 before the upgrade.
RoomsPerSource 16 1 to 10^8 Different rooms one source’s connections are in. A join to one more: 4005.
NewRoomsPerSourcePerHour 10 1 to 10^6 Rooms one source creates in an hour (fixed window). Beyond: 4006, the message dropped, the room not stored.
StoredRooms 0 0 to 10^9 Rooms with files on disk. 0: no limit. The first write of one more: 4007, dropped. Writes to stored rooms are never refused. See “Disk”.

Two limits are the protocol’s and have no setting: the client’s hello is 34 bytes (4003 for another length, 4009 for another version; it must arrive whole within 10 seconds), and an ephemeral message is at most 1024 bytes (4001). At most 16 ephemeral messages per connection are passed on in a second; the rest are dropped (papyr.relay.ephemeral.dropped).

A source is a client’s IPv4 address or the first 64 bits of its IPv6 address: the connection’s address, or behind a trusted proxy the forwarded one. Counts per source live in memory only; no address is logged. Users behind one address (an office, a school, a carrier’s NAT) share one source’s limits. For an instance of one person, or a tool on one machine, set them to the server’s: Papyr__Relay__ConnectionsPerSource=256 Papyr__Relay__RoomsPerSource=1000 Papyr__Relay__NewRoomsPerSourcePerHour=1000000.

A Unix-socket listener makes every client one source. A connection that arrives on a Unix socket (--urls http://unix:/run/papyr.sock) has no remote address, so all of them are the same source, Papyr:TrustedProxies has no peer address to match and does nothing, and the per-source limits become the server’s: by default 32 relay connections, 16 rooms and 10 new rooms an hour for everyone together. Behind a proxy on a Unix socket, raise ConnectionsPerSource, RoomsPerSource and NewRoomsPerSourcePerHour as for one machine above (or listen on TCP, where the proxy’s address and X-Forwarded-For tell the clients apart).

ReceiveBytes is shared among the sources connected: each holds at most the budget divided by their number, a quarter from four sources on, and never less than the largest message. A source that stalls large messages leaves the others three quarters of the budget.

The server’s hello tells each client UpdateBytes and SnapshotBytes; lower values make large edits fail.

Blobs

Papyr:Blobs:<Name>; as environment variables Papyr__Blobs__<Name>. The images of a room (later any file), stored encrypted beside its text; on the wire: spec/relay-protocol.md, “Blobs”. Off unless Enabled is true: every blob route then answers 404 and the page says so when an image is pasted or added. blobs/ is made in the data directory, under its lock, whether or not blobs are on.

Setting Default Range The site What it does
Enabled false true or false true Whether the server takes blobs at all.
BlobBytes 5242880 64 to 1 GiB, at most RoomBytes 2097152 Largest blob, as stored (the file’s size + 29). Beyond: 413.
RoomBlobs 256 1 to 10^6 64 Blobs one room holds. Beyond: 507.
RoomBytes 52428800 at most TotalBytes 16777216 Bytes of blobs one room holds. Beyond: 507.
TotalBytes 1073741824 at least RoomBytes 67108864 Bytes of blobs the server holds in all, uploads in progress included. Beyond: 507. See “Disk”.
UploadsPerSourcePerHour 60 1 to 10^6 30 Uploads one source makes in an hour (fixed window, as NewRoomsPerSourcePerHour). Beyond: 429.

An invalid value, or BlobBytes above RoomBytes above TotalBytes, stops the start with a message that names the setting.

Memory

The defaults allow far more than a small machine has; self-hosting.md, “What to set on a public instance”, gives values for 256 MB. The worst case the limits allow, every term at once, is

10 MiB + ServerConnections x 273 KiB + 2 x ReceiveBytes
       + LoadedRooms x (2 x StoredBytes + QueuedBytes + UpdateBytes + 48 KiB)
       + 4 x 0.5 MiB
       + addresses x HttpConnections x 112 KiB
with TLS on, beside that:
       + ServerConnections x 53 KiB + HttpConnections x 180 KiB

where addresses are those the HTTP listener binds (http://*:8080 is one, localhost two). Keep the sum at or below 75 % of the heap limit, which in a container is 75 % of the container’s memory. A room that is only being typed in holds far less than its share (2000 updates of 100 bytes: 234 KB), so many more rooms fit in practice. What each term is: spec/relay-server.md, “Memory”.

A blob slot holds no buffer of ours (an upload is copied from the request to a file, a download from the file to the response, in the blocks the HTTP server hands out), so blobs add no term to this sum.

The term 4 x 0.5 MiB is for static files: the web root is Brotli-compressed only, and a client that does not accept Brotli (curl, a browser on plain HTTP) gets each file decompressed as it is sent, at most 4 at once. A fifth request waits up to 5 seconds, then gets 503 with Retry-After: 5. A decompression whose client stops reading, or reads slower than 64 KiB/s after 30 seconds, is cut off (telemetry.md, papyr.static.decompression.*). Browsers over HTTPS accept Brotli and need none.

An example, deploy/site.Dockerfile (the general image sets none of these), is sized for 256 MB and 0.5 CPU, a heap limit of 192 MiB, so at most 144 MiB:

Setting Value Term
LoadedRooms 10 51.9 MiB
StoredBytes 1114112 (1.0625 MiB) the least for 1 MiB updates
QueuedBytes 2113568 the least the server takes
ServerConnections 150 40.0 MiB
Papyr:HttpConnections 128 14.0 MiB on its one address; only the proxy connects
ReceiveBytes 8388608 16 MiB: one 8 MiB snapshot at a time
UpdateBytes, SnapshotBytes defaults what the clients assume

Sum: 10 + 40.0 + 16 + 51.9 + 2 + 14.0 = 133.9 MiB, 69.7 % of 192 MiB. Its proxy terminates TLS; with TLS on, the sum would be 164.2 MiB (85.5 %) and need lower limits. deploy/site.Dockerfile carries the same sum in a comment; change both together.

Disk

Put the data directory on a disk-backed volume, never a tmpfs: a tmpfs counts against the container’s memory, and the OOM kill that follows loses every room.

Writes to stored rooms are never refused, so only StoredRooms bounds the rooms’ part of the data directory. The worst case:

StoredRooms x (SnapshotBytes + StoredBytes) + ReceiveBytes + LoadedRooms x StoredBytes + Blobs:TotalBytes

Blobs:TotalBytes bounds blobs/; the temporary files of uploads in progress are reserved inside it. With blobs off the directory stays empty.

With StoredRooms 1000 and the other defaults, about 17 GiB (16 for the rooms, 1 for the blobs). The default is no limit, for a server of one person or a team; a shared instance sets StoredRooms. A room that is only typed in holds far less (a snapshot of a few KB and its log). Not in the sum: a log that grows while its rewrites keep failing (a failing disk only).

The same image is sized for a /data quota of 1 GB (954 MiB):

Setting Value Why
StoredRooms 85 85 x (8 + 1.0625) MiB + 8 MiB + 10 x 1.0625 MiB = 789 MiB (100 without blobs: 925 MiB)
Blobs:TotalBytes 64 MiB (the site column of “Blobs” above) the images: 64 MiB, so 85 x 9.0625 + 8 + 10.6 + 64 = 853 MiB of 954
RoomsPerSource 4 the four kinds of room the start page offers
ConnectionsPerSource 32 (default) one address can fill a room
NewRoomsPerSourcePerHour 10 (default) trying every editor and a sealed room is 4 to 5
RoomExpiryDays 30 a room outlives a holiday
TrustedProxies the build argument TRUSTED_PROXIES operations.md, “Behind a proxy”

What the limits do not stop. A place among the stored rooms costs a single byte, and the hour of NewRoomsPerSourcePerHour is a fixed window per source that starts with the process (a restart forgets every count). One source takes 10 places per window, so all 85 places in eight to nine hours; ten sources take them within seconds, and a home IPv6 /56 is 256 sources. One small write per room every 30 days then keeps them stored. Idle connections hold loaded rooms as cheaply. What to do then: operations.md, “When the limits are held full”.