Self-hosting Papyr
Papyr is one container with one volume: no database, no other service. This page takes you from nothing to an
instance on the internet; CI runs every command here against the image. Reference:
configuration.md, operations.md (the data directory, backup, expiry),
admin-api.md, telemetry.md. To put the relay in an app of your own:
hosting.md.
Quick start
The image ghcr.io/msallin/papyr is published for x64 and arm64 (ARMv8.1 or later: a Raspberry Pi 5 runs it, a Pi 4
does not), tagged 1.2.3, 1.2 and latest for each release. To run a commit that is not a release, build the image
(Building the image) and use papyr where this page says ghcr.io/msallin/papyr:latest.
docker run -d --name papyr --restart unless-stopped -p 8080:8080 -v papyr-data:/data ghcr.io/msallin/papyr:latest
Open http://localhost:8080. docker ps shows healthy within a minute. Pin a version tag
(ghcr.io/msallin/papyr:0.2.0) where an upgrade must not come by itself.
The defaults keep every room for ever and bound nothing on disk. That suits you and your team; for an instance anyone
can reach, read What to set on a public instance. Every room needs HTTPS (or
localhost), because browsers give the encryption API only to secure pages: http://192.168.1.20:8080 opens no room.
What you as the operator can and cannot read: privacy.md.
The same as Compose, deploy/compose.yaml:
services:
papyr:
image: ghcr.io/msallin/papyr:latest
restart: unless-stopped
ports:
- "8080:8080" # "127.0.0.1:8080:8080" when a proxy on this host is the only client
volumes:
- papyr-data:/data # the rooms; never a tmpfs
# The image has its own health check (docker compose ps shows "healthy").
# environment: # the settings people change first, as environment variables
# Papyr__RoomExpiryDays: "30" # remove a room nobody wrote to for 30 days (0: keep every room)
# Papyr__Relay__StoredRooms: "500" # at most 500 rooms on the disk (0: no limit)
# Papyr__TrustedProxies: "172.28.0.0/24" # the network of the proxy in front, if there is one
volumes:
papyr-data:
docker compose -f deploy/compose.yaml up -d
Every setting is an environment variable: the name with __ for each : (Papyr:Relay:StoredRooms is
Papyr__Relay__StoredRooms). A wrong value stops the container; docker logs papyr names the setting and what to
set instead.
Building the image
Without the registry, or to run a commit that is not a release:
git clone https://github.com/msallin/papyr.git && cd Papyr
docker build -t papyr .
The first build takes a few minutes and needs nothing but Docker. The image is about 50 MB: one native binary on a base
without a shell. The Dockerfile builds for x64 only; the published image has an arm64 variant too, which the release
workflow assembles from a cross-compiled binary. To run your build on another host:
docker save papyr | ssh host docker load.
Behind a reverse proxy
A proxy gives you HTTPS with certificates it renews, and one place for several sites. What it must do for Papyr:
| Rule | Why |
|---|---|
Pass the WebSocket upgrade on /relay. |
Every room page holds one WebSocket to /relay; the room is named inside it. |
Pass the Host the browser sent, port included, in the form of a host name (ASCII; a name with _, such as a container’s, is refused). |
The relay refuses (403) a WebSocket whose Origin is not the request’s own host. A proxy that sends its own name or drops the port has every page refused (“Reconnecting…”, then “Offline”; event 33 in the log). Caddy and Traefik pass it; YARP needs RequestHeaderOriginalHost, nginx proxy_set_header Host $http_host. A proxy that cannot pass it needs the site’s origin in Papyr__Relay__AllowedOrigins=https://papyr.example.com. |
| Keep an idle WebSocket open for 30 seconds. | The server pings every 15 s. A shorter idle timeout closes every idle editor. |
Set Papyr__TrustedProxies to the proxy’s network. |
Behind a proxy every connection comes from the proxy, so without it all users share one source’s limits (16 rooms, 32 connections by default) and the next user gets 4005. With it Papyr takes the client’s address from the last entry of X-Forwarded-For, from these peers only. Name the network the proxy is in, nothing wider. |
| Do not compress. | The server sends its pages Brotli-compressed already. Leave encode, gzip and compress off. |
Keep Papyr’s Cache-Control; cache only what it marks immutable. |
Scripts and style sheets have the hash of their content in their names (room.3f2a9c1d0b7e4a56.js) and are sent public, max-age=31536000, immutable: a proxy or CDN may keep them as long as it likes, and browsers ask for them once. The pages (/, /r, /admin) are sent no-cache: a cache that keeps a page past an upgrade serves names that the new version no longer has. A proxy that sets no caching of its own does this already. |
| Pass WebSocket messages up to 8 MiB. | A snapshot of a large room is one message of up to 8 MiB. Request-body limits do not count WebSocket messages; the four examples passed an 8 MB snapshot without a setting. |
Keep /api and /admin off the public site. |
They answer to a token only; keep them inside anyway (admin-api.md, “Keep /api inside”). The examples answer 404. |
Send Strict-Transport-Security: max-age=31536000. |
Papyr sends it itself only when it terminates TLS; behind a proxy it sees plain HTTP and the proxy must. A browser then refuses plain HTTP to the site, so a link without a scheme cannot reach an on-path attacker’s look-alike page. Caddy: header Strict-Transport-Security "max-age=31536000"; nginx: add_header Strict-Transport-Security "max-age=31536000" always;; Traefik: the label traefik.http.middlewares.hsts.headers.stsSeconds=31536000 on a middleware the router uses; YARP: the route transform { "ResponseHeader": "Strict-Transport-Security", "Append": "max-age=31536000", "When": "Always" }. The examples below set it. Add includeSubDomains or preload only when every subdomain serves HTTPS and you mean to stay. |
| Terminate TLS. | Papyr speaks plain HTTP behind the proxy. |
All four examples assume the proxy and Papyr are containers on one Docker network, Papyr is called papyr, and
the site is papyr.example.com. Create the network and start Papyr on it, trusting that network:
docker network create papyr-net
docker run -d --name papyr --restart unless-stopped --network papyr-net -v papyr-data:/data \
-e Papyr__TrustedProxies="$(docker network inspect papyr-net --format '{{(index .IPAM.Config 0).Subnet}}')" \
-p 127.0.0.1:8080:8080 ghcr.io/msallin/papyr:latest
The port is published on loopback only, for you: the admin page and API answer there (an SSH tunnel to port 8080
brings them to your computer). Never publish it on a public address: a connection through a published port comes from
the network’s gateway, inside the trusted network, so a client could write any X-Forwarded-For.
For a proxy on the host rather than in a container, point it at 127.0.0.1:8080 and set Papyr__TrustedProxies to
the address Papyr sees it at. That is not 127.0.0.1 but the gateway of Docker’s bridge network (docker network
inspect bridge, field Gateway), which differs between Docker setups (rootless Docker and Podman use others). Verify
with “Check it”.
YARP
YARP is Microsoft’s reverse proxy for .NET: a small ASP.NET Core app you can read and
change. deploy/examples/yarp/ holds the app (a file-based app of .NET 11) and its image.
Kestrel serves HTTPS with a certificate from certbot; get it first, while nothing listens on port 80
(sudo certbot certonly --standalone -d papyr.example.com).
Proxy.cs:
using Yarp.ReverseProxy.Configuration;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddReverseProxy().LoadFromMemory(
[
new RouteConfig
{
RouteId = "papyr",
ClusterId = "papyr",
Match = new RouteMatch { Path = "{**path}" },
Transforms =
[
// Pass the Host the browser sent, port included: Papyr refuses a page whose Origin is another host.
new Dictionary<string, string> { ["RequestHeaderOriginalHost"] = "true" },
// Replace any X-Forwarded-For a client sent with its own address.
new Dictionary<string, string> { ["X-Forwarded"] = "Set" },
// A browser that saw the site over HTTPS refuses plain HTTP to it for a year.
new Dictionary<string, string> { ["ResponseHeader"] = "Strict-Transport-Security", ["Append"] = "max-age=31536000", ["When"] = "Always" },
],
},
],
[
new ClusterConfig
{
ClusterId = "papyr",
Destinations = new Dictionary<string, DestinationConfig>
{
["papyr"] = new() { Address = "http://papyr:8080" },
},
},
]);
var app = builder.Build();
app.UseHttpsRedirection();
// The admin page and API stay off the public site.
app.Use((context, next) =>
{
if (context.Request.Path.StartsWithSegments("/api") || context.Request.Path.StartsWithSegments("/admin"))
{
context.Response.StatusCode = StatusCodes.Status404NotFound;
return Task.CompletedTask;
}
return next(context);
});
// WebSockets pass without a setting; YARP neither compresses nor closes a WebSocket that the server pings.
app.MapReverseProxy();
app.Run();
Dockerfile:
FROM mcr.microsoft.com/dotnet/sdk:11.0 AS build
WORKDIR /src
COPY Proxy.cs .
RUN dotnet publish Proxy.cs -c Release -o /app
FROM mcr.microsoft.com/dotnet/aspnet:11.0
WORKDIR /app
COPY --from=build /app .
ENTRYPOINT ["dotnet", "Proxy.dll"]
docker build -t papyr-yarp deploy/examples/yarp
docker run -d --name yarp --restart unless-stopped --network papyr-net -p 80:80 -p 443:443 \
-e Kestrel__Endpoints__Http__Url=http://*:80 -e Kestrel__Endpoints__Https__Url=https://*:443 \
-e Kestrel__Endpoints__Https__Certificate__Path=/etc/letsencrypt/live/papyr.example.com/fullchain.pem \
-e Kestrel__Endpoints__Https__Certificate__KeyPath=/etc/letsencrypt/live/papyr.example.com/privkey.pem \
-v /etc/letsencrypt:/etc/letsencrypt:ro papyr-yarp
Kestrel reads the certificate at its start: renew with certbot’s timer plus a restart of the proxy
(--deploy-hook "docker restart yarp"). RequestHeaderOriginalHost passes the browser’s Host; X-Forwarded set to
Set writes the client’s address and drops whatever a client sent.
Caddy
Caddy gets and renews the certificate from Let’s Encrypt itself; the DNS name must point at the host and ports 80 and
443 must be open. deploy/examples/Caddyfile:
papyr.example.com {
# A browser that saw the site over HTTPS refuses plain HTTP to it for a year.
header Strict-Transport-Security "max-age=31536000"
# The admin page and API stay off the public site; ask them on the container's own port, or through an SSH tunnel.
@inside path /api /api/* /admin /admin/*
respond @inside 404
# The WebSocket upgrade of /relay needs no setting, and an idle WebSocket is not closed.
# No `encode`: the server sends its files compressed already.
reverse_proxy papyr:8080
}
docker run -d --name caddy --restart unless-stopped --network papyr-net -p 80:80 -p 443:443 \
-v "$PWD/Caddyfile:/etc/caddy/Caddyfile:ro" -v caddy-data:/data caddy:2
Caddy sets X-Forwarded-For itself and passes the Host as the browser sent it.
nginx
deploy/examples/nginx.conf needs certbot’s certificate. Get it first, while nothing
listens on port 80 (sudo certbot certonly --standalone -d papyr.example.com), and renew it with certbot’s timer plus
a reload (--deploy-hook "docker exec nginx nginx -s reload").
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
server_name papyr.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
http2 on;
server_name papyr.example.com;
ssl_certificate /etc/letsencrypt/live/papyr.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/papyr.example.com/privkey.pem;
# A browser that saw the site over HTTPS refuses plain HTTP to it for a year.
add_header Strict-Transport-Security "max-age=31536000" always;
# The admin page and API stay off the public site.
location ~ ^/(api|admin)(/|$) { return 404; }
location / {
proxy_pass http://papyr:8080;
proxy_http_version 1.1;
proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
# A WebSocket silent for this long is closed. The server's pings every 15 s count as traffic.
proxy_read_timeout 1h;
proxy_send_timeout 1h;
}
}
docker run -d --name nginx --restart unless-stopped --network papyr-net -p 80:80 -p 443:443 \
-v "$PWD/nginx.conf:/etc/nginx/conf.d/default.conf:ro" -v /etc/letsencrypt:/etc/letsencrypt:ro nginx:1
Host $http_host passes the browser’s Host with its port ($host drops it). Upgrade and Connection are not
passed by default; without them the upgrade fails and the editor shows a closed connection at once.
Traefik
Traefik finds Papyr through the Docker socket and the labels on its service, so this is one Compose file,
deploy/examples/traefik-compose.yaml. It gets the certificate from Let’s
Encrypt (change the e-mail address). The network has a fixed subnet so that Papyr__TrustedProxies can name it.
services:
traefik:
image: traefik:v3
restart: unless-stopped
command:
- --providers.docker=true
- --providers.docker.exposedbydefault=false
- --entrypoints.web.address=:80
- --entrypoints.web.http.redirections.entrypoint.to=websecure
- --entrypoints.web.http.redirections.entrypoint.scheme=https
- --entrypoints.websecure.address=:443
- --certificatesresolvers.le.acme.email=you@example.com
- --certificatesresolvers.le.acme.storage=/letsencrypt/acme.json
- --certificatesresolvers.le.acme.tlschallenge=true
ports:
- "80:80"
- "443:443"
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- traefik-acme:/letsencrypt
papyr:
image: ghcr.io/msallin/papyr:latest
restart: unless-stopped
volumes:
- papyr-data:/data
environment:
Papyr__TrustedProxies: 172.28.0.0/24 # the network below: only Traefik is in it
labels:
traefik.enable: "true"
# /api and /admin are not routed, so Traefik answers them with 404.
traefik.http.routers.papyr.rule: Host(`papyr.example.com`) && !PathPrefix(`/api`) && !PathPrefix(`/admin`)
traefik.http.routers.papyr.entrypoints: websecure
traefik.http.routers.papyr.tls.certresolver: le
# A browser that saw the site over HTTPS refuses plain HTTP to it for a year.
traefik.http.routers.papyr.middlewares: hsts
traefik.http.middlewares.hsts.headers.stsSeconds: "31536000"
traefik.http.services.papyr.loadbalancer.server.port: "8080"
networks:
default:
ipam:
config:
- subnet: 172.28.0.0/24
volumes:
papyr-data:
traefik-acme:
docker compose -f traefik-compose.yaml up -d
To reach the admin page and API, add ports: ["127.0.0.1:8080:8080"] to the papyr service. The Docker socket
gives Traefik control of Docker, read-only or not; if that is more than you want, use Traefik’s file provider with the
same router and service.
Check it
From two computers behind different addresses (a phone off Wi-Fi and a laptop), open rooms until one is refused: each
should have its own limit (RoomsPerSource, 16 by default). If the second computer is refused with the first one’s
rooms, Papyr__TrustedProxies does not name the address the proxy connects from. The check with a forged header:
operations.md, “Behind a proxy”. tests/docs/check-proxy.sh runs each example against the image.
Without a proxy: TLS in Papyr itself
For one site on one host, Papyr serves HTTPS itself from PEM files (configuration.md, “TLS”).
It fetches no certificate (get it with certbot) and redirects nothing from http:// to https:// (publish only the
HTTPS port).
The container’s user, uid 1654, must read both files. Certbot’s privkey.pem is root’s, so copy the files in a deploy
hook, which runs after each issue and renewal:
sudo certbot certonly --standalone -d papyr.example.com --deploy-hook \
'install -d -m 0755 /srv/papyr-tls && install -o 1654 -m 0600 "$RENEWED_LINEAGE/fullchain.pem" "$RENEWED_LINEAGE/privkey.pem" /srv/papyr-tls/'
docker run -d --name papyr --restart unless-stopped -v papyr-data:/data -v /srv/papyr-tls:/tls:ro \
-e Papyr__Tls__CertificatePath=/tls/fullchain.pem -e Papyr__Tls__KeyPath=/tls/privkey.pem \
-p 443:8443 ghcr.io/msallin/papyr:latest
The image listens for TLS on 8443 (uid 1654 cannot bind 443), so -p 443:8443 maps it. Do not publish 8080, the plain
HTTP listener. A renewed certificate is picked up within a minute, without a restart. /api and /admin answer on the
HTTPS port as well; with a token set, the token alone guards them there (admin-api.md, “Keep /api
inside”).
Over HTTPS the server sends Strict-Transport-Security: max-age=31536000 (a year, without includeSubDomains or
preload): browsers that saw the site once over HTTPS refuse plain HTTP to it afterwards. Before the first HTTPS visit
a browser has no such memory, so redirect or close port 80 as you see fit.
What to set on a public instance
The defaults suit one person or a team: every room is kept (RoomExpiryDays 0), any number of rooms is stored
(StoredRooms 0), and the limits are sized for a large machine. On a public instance a stranger can fill the disk, so
set at least:
| Setting | Why | Example |
|---|---|---|
Papyr__RoomExpiryDays |
A room nobody wrote to for this long is removed. Reading does not keep a room. | 30 |
Papyr__Relay__StoredRooms |
The most rooms on the disk; a new room beyond it is refused (4007) while the stored ones go on. The disk’s worst case follows from it (configuration.md, “Disk”). |
100 |
Papyr__TrustedProxies |
Behind a proxy: see above. | the proxy’s network |
On a small VM, bound the memory as well. These are the values of deploy/site.Dockerfile,
sized for a container of 256 MB and a data volume of 1 GB; configuration.md, “Memory” and “Disk”, derive them. As
Compose:
mem_limit: 256m
environment:
Papyr__RoomExpiryDays: "30"
Papyr__Relay__StoredRooms: "85"
Papyr__Relay__LoadedRooms: "10"
Papyr__Relay__ServerConnections: "150"
Papyr__HttpConnections: "128"
Papyr__Relay__StoredBytes: "1114112"
Papyr__Relay__QueuedBytes: "2113568"
Papyr__Relay__ReceiveBytes: "8388608"
Papyr__Relay__ConnectionsPerSource: "32"
Papyr__Relay__RoomsPerSource: "4"
Papyr__Relay__NewRoomsPerSourcePerHour: "10"
Papyr__Blobs__Enabled: "true"
Papyr__Blobs__BlobBytes: "2097152"
Papyr__Blobs__RoomBlobs: "64"
Papyr__Blobs__RoomBytes: "16777216"
Papyr__Blobs__TotalBytes: "67108864"
Papyr__Blobs__UploadsPerSourcePerHour: "30"
That image runs with images on and StoredRooms 85, so that its disk holds them too. It also lists its own origin
(Papyr__Relay__AllowedOrigins) because its proxy does not pass the Host; behind one of the proxies above, leave it
empty. ConnectionsPerSource, RoomsPerSource and NewRoomsPerSourcePerHour bound what one address can take; users
behind one address share them. For a bigger machine raise LoadedRooms and ServerConnections with the memory,
checked against the sum in configuration.md, “Memory”: a limit too high for the container ends in an OOM kill, which
drops every connection. Papyr__HttpConnections counts the proxy’s connections, not your users’.
A host whose deploy takes an image and no environment needs the values baked in: deploy/site.Dockerfile is a second
image on top of the first. BASE names the first image (default papyr), TRUSTED_PROXIES the proxy’s network:
docker build -f deploy/site.Dockerfile --build-arg TRUSTED_PROXIES=172.28.0.0/24 -t papyr-site deploy
docker build -f deploy/site.Dockerfile --build-arg BASE=ghcr.io/msallin/papyr:0.2.0 -t papyr-site deploy
What the limits do not stop, and what to do then: operations.md, “When the limits are held full”.
Images
Images in rooms are off by default. A picture pasted into a room is encrypted in the browser and stored by the server as
a file it cannot read, beside the room’s text. To turn them on, set Papyr__Blobs__Enabled to true:
environment:
Papyr__Blobs__Enabled: "true"
With the flag off, no blob route answers and the page says so when a picture is pasted. The limits (the largest image 5
MiB, 256 images and 50 MiB per room, 1 GiB in all, 60 uploads per source an hour) and their ranges are in
configuration.md, “Blobs”.
The images are files in blobs/ beside rooms/, so the volume must hold them too: the worst case is in
configuration.md, “Disk”. A backup carries the images and grows by up to TotalBytes; a restore writes them back,
and a restored text without its images shows missing pictures. Turning the flag off keeps the files, in the data
directory and in backups, and serves none of them. A room’s images are removed with the room, when it expires or is
removed through the admin API; nothing else removes one, since the server cannot read which images a text still names.
A proxy in front must allow the upload’s size. nginx refuses a request body above 1 MB by default, and the example on
this page does not raise that: with images on, add client_max_body_size 5m; (at least BlobBytes) to its server
block, or an image above 1 MB gets 413. Caddy, Traefik and YARP need no change.
What the server can see of an image: privacy.md, “Images”.
Embedding
By default no site shows a Papyr page in a frame (Content-Security-Policy: frame-ancestors 'none'). To show the room
page in another site of yours (a wiki, an intranet, Nextcloud, Moodle), list that site’s origin:
environment:
Papyr__Web__FrameAncestors: "https://wiki.example,https://cloud.example:8443"
The start page (/) and the room page (/r) may then be framed by those sites and no other; the frame’s address is
the room’s link, https://papyr.example/r#.... The admin page is never framed. The framed page opens its WebSocket as
its own site, so Papyr:Relay:AllowedOrigins needs no entry. The form of an entry: configuration.md,
Papyr:Web:FrameAncestors.
What listing a site means:
- It can frame, not read. The same-origin policy keeps the embedding page from reading the framed page’s text, keys or input.
- It knows the room. The embedding page writes the frame’s address, which holds the room’s name or secret: its operator and every script it loads know the room. List only sites you trust as much as the people who share the link.
- It can lay out the page (clickjacking). A listed site can cover the frame, make it transparent and get a visitor to click or type into a room they do not see. That is the risk the default refuses, and why the list holds origins only, never a pattern.
- A site is everyone who can publish on it. Listing a wiki or a Moodle gives this to every editor or course author there, not only to its operator.
- Storage is kept per embedding site. In a frame, the recent rooms and the user’s name, colour and view are those of this embedding site; a browser that blocks third-party storage keeps none (the page works without remembering).
- Copying the link in a frame needs
<iframe allow="clipboard-write">; without it the share panel says to copy the link from the address bar, which in a frame shows the embedding page’s.
Jitsi Meet’s shared document (etherpad_base) does not work with Papyr: Jitsi puts the document’s name into the
path, and Papyr names a room in the fragment.
Languages
The start page and the room page are in English or German, by the browser’s language unless the user chooses (the footer of the start page, the More menu of a room); the admin page is English. Nothing to set on the server.
The admin API and page
With a token set, /api answers the server’s status, the stored rooms (list, remove) and a backup; /admin is a page
for the same. Without one there is no /api. How to set the token and every route: admin-api.md.
Keep both off the public site (the proxy examples do).
Backup and restore
A plain copy of the data directory while the server runs is not safe. Take the backup, a consistent tar streamed while the server runs, and restore it into an empty volume with the binary itself:
curl -sS -f -H "Authorization: Bearer $(cat papyr-admin-token)" -o backup.tar http://127.0.0.1:8080/api/backup
docker run --rm -i -v papyr-data-new:/data ghcr.io/msallin/papyr:latest restore < backup.tar
The other safe ways, scheduled backups and what a restore refuses: operations.md, “Backup and
restore”.
Upgrading
Back up first. Then pull the new image (or build it from an updated clone) and start the container again from it; the volume stays:
docker compose pull && docker compose up -d # or: docker pull ghcr.io/msallin/papyr:0.2.0, docker rm -f papyr, then the same docker run
Before 1.0 a new version may change the settings, the addresses, the protocol and the file format without a migration:
a stored room may become unreadable, and open pages are told to reload. Every such change is a commit marked feat!:,
fix!: or build!: whose body says what to change. Read those between the version you run (/api/status shows its
commit after the +) and the one you build:
git log --extended-regexp --grep='^[a-z]+!:' --format='%h %s%n%b' OLD_COMMIT..HEAD
After going back to an older image and then forward again: if the older image predates rooms/.format-5 (the mark
below), remove it before you start this version again, so that it checks every room file once more:
docker run --rm -v papyr-data:/data alpine rmdir /data/rooms/.format-5
An image that knows the mark removes a newer version’s at its start, and nothing is needed.
From room files of an earlier version
The first start of this version on a data directory reads the header of every room file, and the server does not start
when one is of an earlier version. docker logs papyr shows which, each named by its room’s tag (the first 8
characters of its name):
Papyr.Server: The room directory '/data/rooms' holds room files of an earlier version (3, beside 0 of this version), which this version of Papyr does not read. The server did not start, and nothing was changed. Export the text of each of those rooms with the image that wrote them (each room's More, Export), then remove those files, and only those, from the directory and start again: Ab3dEf9x*.log, Ab3dEf9x*.snapshot, Kq7mN2pL*.log.
This happens on an upgrade from a version that wrote another room format (plenum-room-log 4 and earlier, written under
the name Plenum; this version writes papyr-room-log 5). Before you upgrade, while the old image still runs:
- Export what you want to keep: open each room (its link, or an open room’s name) and use More (⋯), Export. A sealed room’s text only its members can export: tell them. The rooms that exist are on the admin page.
-
Stop the container and remove the room files the message names (every room file, when the format changed), or start the new version on a new, empty volume:
docker stop papyr docker run --rm -v papyr-data:/data alpine sh -c 'rm -f /data/rooms/*.log /data/rooms/*.snapshot /data/rooms/*.tmp' - Start the new image. Open new rooms and import the exported files (More, “Import a file”).
Once a start has found no such file it leaves the empty directory rooms/.format-5, and later starts no longer read
the headers; what that means for files that come in later: operations.md, “The data directory”.
restore refuses a backup that holds such files as a whole. A page of an earlier version still open when the server
is upgraded is told to reload (4009).
Moving to another host
Take a backup on the old host and restore into the new host’s empty volume (“Backup and restore”); that keeps the files’ times and so the expiry. Without the admin API: stop the container, copy the volume, and give the files to uid 1654:
docker stop papyr
docker run --rm -v papyr-data:/data:ro -v "$PWD:/out" alpine tar cf /out/data.tar -C /data .
# on the new host, with data.tar in the current directory:
docker run --rm -v papyr-data:/data -v "$PWD:/in:ro" alpine sh -c 'tar xf /in/data.tar -C /data && chown -R 1654:1654 /data'
Never run two servers on one data directory, nor one volume mounted from two hosts.
Coming from Etherpad
Papyr does one thing Etherpad does: several people edit one text together, in real time. It is not a drop-in replacement and does not read an Etherpad database.
What Papyr has. One Markdown editor (CodeMirror) with highlighting, the others’ carets, a toolbar and a preview.
Every user has a name and a colour, no accounts. A room is made by opening a link, and whoever has the link can read
and edit. Rooms expire (Papyr__RoomExpiryDays). An admin page and API. One directory of files to back up. A new
room gets a readable name of three words and four random characters (quiet-amber-otter-k7q2, about 2^41 names:
hard to guess, not secret); the start page lists the rooms your browser opened (kept in the browser only).
- Import and export: More (⋯) exports the text as
.mdor.txtand the preview as a standalone HTML file, and imports a.mdor.txtfile (UTF-8, up to 6 MiB), replacing the text or inserting at the caret. - Authorship colours, on by default (More, “Hide authorship colours” hides them for you): each other user’s text has a light background of their colour and their name on hover, also after they left, until someone chooses More, “Clear authorship colours…”. They are a convenience, not evidence: any member can write under another’s name, change anyone’s colours, or clear them all.
- Versions: More, “Save a version…” keeps the text as it is (up to 20 versions and 1 MiB together, sealed with the room); “Versions” shows one, its changes against now, and restores it. A version is saved by itself before an import that replaces the text and before a restore.
What it does not have, and will not: a time slider replaying every keystroke; rich text; plugins, chat, comments;
accounts, logins or read-only links (access is “who has the link”); a list of rooms for everyone (a room is found by
its link or name; the admin page lists rooms by id); reading an Etherpad database or its /p/<name>/export links
(export a pad as text or Markdown, open the room by the same name and import the file). The More menu exports in the browser; there is no export over HTTP.
What is different.
- A room is whoever has the link. An open room (
/r#notes) is named in the link, and its name is its only secret: anyone who knows or guesses it can read and change the room, the operator included. A sealed room (/r#s.<secret>) holds a random secret that nobody can guess (privacy.md). - Etherpad’s
/p/<name>is/r#<name>. The name is in the fragment, which the browser never sends to the server. It is not the Etherpad pad of that name, and old links do not redirect. - The operator’s page is
/adminand its API is/apiwith a bearer token; Etherpad’s HTTP API and settings file do not exist. Settings are environment variables (configuration.md). - One instance, no clustering, no database: the rooms are files in one directory.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| The container exits at the start. | docker logs papyr. A wrong setting stops the start with one line that names it: Papyr.Server: The setting Papyr:RoomExpiryDays is 'forever'. Set it (or the environment variable Papyr__RoomExpiryDays) to a whole number from 0 to 36500, or remove it to use 0. |
The data directory '/data' (Papyr:DataDirectory) cannot be written by the user the server runs as. |
A bind mount owned by another user than uid 1654: sudo chown 1654 /srv/papyr. |
| The start names room files of an earlier version. | “From room files of an earlier version”. |
| A room is answered as damaged, “of an earlier version” (event 11). | A file of an earlier version came in after the first start’s check: “From room files of an earlier version”. |
| Behind a proxy no page ever syncs; the log has event 33. | The proxy does not pass the Host the browser sent (nginx: proxy_set_header Host $http_host), or the page is on another site. Pass the Host, or list the page’s origin in Papyr__Relay__AllowedOrigins. |
| The editor says the connection is closed at once, behind a proxy. | The upgrade fails: the proxy does not pass Upgrade and Connection (nginx needs the two proxy_set_header lines and proxy_http_version 1.1), or closes a connection silent for under 30 s. Test without the proxy on Papyr’s own port. |
| Everyone shares one limit; one visitor’s rooms use up the others’. | Papyr sees the proxy’s address for everyone: Papyr__TrustedProxies is missing or wrong (event 19 once per start). Name the proxy’s network, no wider. |
What users see. A page shows why it stopped syncing from the close status the server sent:
| Status | Meaning | What to do |
|---|---|---|
| 4005 | Too many connections or rooms from one address. | Raise the limits per source, or check the trusted proxies. |
| 4006 | Too many new rooms from one address in the last hour. | Wait, or raise NewRoomsPerSourcePerHour. |
| 4007 | The server stores no more rooms. | Raise StoredRooms, set an expiry, or remove rooms. |
| 4000, 4004 | The room or the server is full. | Wait. |
| 4008 | The operator removed the room. | |
| 4009 | The page is of another version than the server. | Reload the page. |
| 1006, no notice | The connection was cut: the proxy, the network, a connection over its limit (429 before the upgrade), or a page refused for its Origin (403). |
The contract: spec/relay-protocol.md, “Close statuses”.