Self-hosting with Docker

Plotra is open source (AGPL-3.0) and everything in it runs on your own machine. One compose file starts the whole thing:

A self-hosted Plotra has no limits on projects or storage, needs no account anywhere, and sends no email unless you set that up.

RequirementsCopy Anchor Link

• Docker with Compose v2.20 or newer (docker compose version).
• About 2 GB of free memory to build the app image, and 1 GB to run the stack.
• git and openssl.
• For anything other than http://localhost: a domain name and a reverse proxy that does TLS. See Reverse proxy and TLS.

Quick startCopy Anchor Link

git clone https://github.com/ItzSudhan/plotra.git
cd plotra/docker
cp .env.example .env

Generate the secrets. This fills every empty secret in .env, and leaves filled ones alone if you run it again:

for name in POSTGRES_PASSWORD BETTER_AUTH_SECRET COLLAB_SECRET S3_SECRET_ACCESS_KEY AI_KEY_SECRET; do
  sed -i.bak "s|^$name=\$|$name=$(openssl rand -hex 32)|" .env
done && rm -f .env.bak

Start it:

docker compose up -d --build

The first run builds three images and takes a few minutes. When docker compose ps shows app and collab as healthy, open http://localhost:3000 and sign up with an email and a password. The first account is an ordinary account: there is no admin user to set up.

To check the instance from the command line:

curl http://localhost:3000/api/health
curl http://localhost:8787/health

The first answers {"ok":true,"database":"ok",…} and lists which optional services are configured. The second is the collab server, and answers {"ok":true}.

SettingsCopy Anchor Link

Everything is set in docker/.env. After changing a value, run docker compose up -d again. The two settings marked "build" are compiled into the app, so they need docker compose up -d --build app.

AddressesCopy Anchor Link

If you change APP_PORT without a reverse proxy, change the port in BETTER_AUTH_URL to match. The same goes for COLLAB_PORT and NEXT_PUBLIC_COLLAB_URL.

SecretsCopy Anchor Link

What runsCopy Anchor Link

FilesCopy Anchor Link

Uploads and version snapshots go to an S3-compatible store. The bundled one is MinIO; the defaults in .env point at it.

Nothing outside the stack talks to the store: the app reads and writes files on behalf of browsers. That is why MinIO has no published port.

To use another S3 store (Garage, SeaweedFS, AWS S3), set the five S3_ values and remove minio from COMPOSE_PROFILES. Create the bucket yourself.

To run with no store at all, also empty S3_ENDPOINT. Files then go into Postgres, with smaller limits: 10 MB a file and 100 MB a project.

LimitsCopy Anchor Link

The hosted version sets these so it can stay free. See Limits on the hosted version.

Sign-in and emailCopy Anchor Link

Email and password sign-in works with nothing else set up. Anyone who can reach your instance can sign up. They get their own workspace and see nothing of yours, but if you don't want strangers on it, don't expose it to the internet, or put your reverse proxy's access control in front of it.

Without RESEND_API_KEY no email is sent. Each invitation or sharing link is written to the app's log instead, and you pass it on yourself:

docker compose logs app | grep '\[plotra\]'

[plotra] Invitation for grace@example.com to Test Press: http://localhost:3000/invite/WNHMQN8S…

AICopy Anchor Link

The AI agent never runs on a key of the project's. Each person adds their own provider key in Settings, which needs AI_KEY_SECRET. Or you give the whole instance one model:

OtherCopy Anchor Link

Why some settings need a rebuildCopy Anchor Link

Next.js compiles every NEXT_PUBLIC_ value into the JavaScript it sends to browsers. They are fixed when the image is built, not when the container starts. The compose file passes them from .env to the build as build arguments, so the image you build carries your values:

docker compose up -d --build app

Everything else is read when the container starts.

Reverse proxy and TLSCopy Anchor Link

Browsers need to reach two things: the app and the collab server's WebSocket. Neither container does TLS, so put a reverse proxy in front.

Browsers only ever talk to the collab server under /parties/, and the app has no pages there. So one domain is enough: send /parties/* to the collab server and everything else to the app.

In .env:

BETTER_AUTH_URL=https://plotra.example.com
NEXT_PUBLIC_COLLAB_URL=https://plotra.example.com
APP_BIND=127.0.0.1
COLLAB_BIND=127.0.0.1

Then rebuild, because NEXT_PUBLIC_COLLAB_URL changed: docker compose up -d --build.

With Caddy, which gets certificates by itself and handles WebSockets without extra settings:

plotra.example.com {
    handle /parties/* {
        reverse_proxy 127.0.0.1:8787
    }
    handle {
        reverse_proxy 127.0.0.1:3000
    }
}

With nginx, inside a server block that already has your certificate:

location /parties/ {
    proxy_pass http://127.0.0.1:8787;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 1h;
}

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    client_max_body_size 110m;
}

Things that matter whichever proxy you use:

• Pass the Host header through and set X-Forwarded-Proto. The app builds its redirects from them.
• Set X-Forwarded-For. Rate limits count by client address. Without it everyone shares one limit.
• Allow WebSocket upgrades and long-lived connections on /parties/.
• Allow large request bodies on the app if you want large uploads.
• Send only /parties/ to the collab server. Browsers need nothing else from it.
• Two domains work as well: point NEXT_PUBLIC_COLLAB_URL at the second one, such as https://collab.plotra.example.com.

The collab container reaches the app directly inside the compose network (http://app:3000), not through your proxy. It still needs BETTER_AUTH_URL to be the public address, because the tokens it checks name that address as their issuer. The compose file passes both.

BackupsCopy Anchor Link

Three volumes hold data, plus your .env:

The database. pg_dump works while the stack is running:

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

The file store. Archive the volume. Stop the store first for a consistent copy:

docker compose stop minio
docker run --rm -v plotra_minio-data:/data:ro -v "$PWD":/backup alpine \
  tar czf /backup/minio-$(date +%F).tar.gz -C /data .
docker compose start minio

The same command with plotra_collab-data copies the collab server's state; stop collab for it.

Restoring the database into a new, empty instance. pg_dump does not include roles, so create the one Plotra's row-level security uses before loading the dump:

docker compose up -d postgres
docker compose exec -T postgres psql -U plotra -d plotra \
  -c "create role plotra_app nologin nobypassrls; grant plotra_app to plotra;"
docker compose exec -T postgres pg_restore -U plotra -d plotra --no-owner < plotra-2026-10-02.dump
docker compose up -d

When you restore an older database into an instance that has been running, remove the collab volume too (docker volume rm plotra_collab-data, with the stack down). Otherwise the collab server still holds the newer text of each note and writes it back over the restored one.

UpgradingCopy Anchor Link

Back up the database first. Then:

git pull
docker compose up -d --build

That rebuilds the images, runs the migrate job, and only then starts the new app: the app waits for migrate to finish, and does not start if a migration fails. Migrations that were already applied are skipped. To see what it did:

docker compose logs migrate

There are no tagged releases yet, so git pull takes the current master. Read the commit log for anything that mentions self-hosting before you upgrade.

Using Neon or another PostgresCopy Anchor Link

The bundled Postgres is optional. To run against Neon instead, create a project there, copy its connection string, and in .env set DATABASE_URL to it and remove postgres from COMPOSE_PROFILES (leaving COMPOSE_PROFILES=minio,collab). Then docker compose up -d --build: the migrate job creates the tables in Neon, and the app connects with Neon's serverless driver, which it picks by itself for a neon.tech host. The pooled and the direct connection string both work. Set DATABASE_DRIVER=pg if you would rather connect over plain TCP, as the migrations do.

The same goes for any other Postgres: set DATABASE_URL, drop the postgres profile. Plotra is developed and tested on Postgres 18; older versions have not been tried. One requirement holds everywhere. The role in the connection string must own the database and be allowed to create roles, because a migration creates plotra_app, the role without privileges that every user request runs as so that Postgres row-level security applies to it. Neon's default role qualifies. On your own server, a superuser does, or a role with CREATEROLE that owns the database.

The self-hosted collab server and its limitsCopy Anchor Link

On the hosted version the collab server is a Cloudflare Worker with one Durable Object per open note. The collab container runs that same worker, unchanged, under workerd, Cloudflare's open-source runtime, started through wrangler dev. Its storage is one SQLite file per note under /data, on the plotra_collab-data volume.

That keeps one codebase for both, and it has limits you should know:

• It is Cloudflare's local development mode. It is the same runtime, but Cloudflare does not offer it as a production server. It has been run here for editing by a few people at once, not under load.
• One process, one machine. It cannot be scaled out by running more copies: two copies would each hold their own version of a note.
• Every open note is held in memory until everyone has left it.
• It builds the worker each time the container starts, which takes a few seconds. The collab service waits for the app to be healthy first.
• It does no TLS. Browsers on an HTTPS page can only connect to it through a proxy that does.
• Its files are in Miniflare's format, which could change with a new major version of wrangler. The version is pinned by the repo's lockfile. Postgres has a copy of every note, so an emptied /data reloads from there.
• It contacts the internet on start to look for a newer wrangler and to fetch request metadata from Cloudflare. Both fail quietly without a connection, and usage reporting is switched off.
• wrangler dev has a debugging interface that can read the stored notes. The container switches it off (X_LOCAL_EXPLORER=false in docker/collab-entrypoint.sh). Keep that setting if you write your own entrypoint, and proxy only /parties/ as shown above.

If these limits matter to you, you can deploy apps/collab to your own Cloudflare account instead (the free plan covers it) and point NEXT_PUBLIC_COLLAB_URL at it. Set its APP_URL to your BETTER_AUTH_URL and its COLLAB_SECRET to yours, and remove collab from COMPOSE_PROFILES. Your app then has to be reachable from the internet, because the worker calls it.

TroubleshootingCopy Anchor Link

To start over and delete all data: docker compose down -v.