Self-Hosting

Self-hosting means running Parchment on your own machine or server. Your data stays with you, and you get all features without relying on a third-party service.

What you need

• A machine or VPS with Docker and Docker Compose installed
• At least 2 GB RAM
• A domain or static IP (optional; recommended for HTTPS and sharing)

Docker configuration

Parchment runs as three containers defined in a Docker Compose file:

Copy the compose file (docker-compose.prod.yml) from the repository.

When running from a clone, the init-postgis.sh path is relative to the repo. When using the download-only method below, either omit that volume or run from a clone for first-time DB init.

Standalone from Docker Compose file

You can run Parchment by cloning the Docker Compose file and environment template:

curl -o docker-compose.prod.yml https://raw.githubusercontent.com/alexwohlbruck/parchment/main/docker-compose.prod.yml
curl -o .env https://raw.githubusercontent.com/alexwohlbruck/parchment/main/.env.example
# Edit .env with your settings
docker compose -f docker-compose.prod.yml up -d

Configure .env as in Environment.

Integrate into an existing Compose stack

To run Parchment alongside other services (e.g. homelab, reverse proxy), use Compose includes so one docker-compose up brings up everything.

Example layout:

homelab/
├── docker-compose.yml    # Your main compose file (includes Parchment)
├── .env                  # Environment variables (add Parchment vars here)
└── parchment/
    └── docker-compose.yml   # Parchment compose (downloaded)

1. Download the Parchment compose file (and optional env template):

mkdir -p parchment
curl -o parchment/docker-compose.yml https://raw.githubusercontent.com/alexwohlbruck/parchment/main/docker-compose.prod.yml
curl -o parchment/.env.example https://raw.githubusercontent.com/alexwohlbruck/parchment/main/.env.example

2. Add Parchment variables to your root .env (copy the ones you need from parchment/.env.example: database, SERVER_ORIGIN, CLIENT_ORIGIN, email).

3. Include Parchment in your main compose file:

# your main docker-compose.yml
include:
  - parchment/docker-compose.yml

4. Start your stack:

docker compose up -d

Parchment will start with the rest of your services. Ensure SERVER_ORIGIN and CLIENT_ORIGIN match how you reach the API and frontend (e.g. through your reverse proxy).

Attaching to a reverse-proxy network

If your proxy runs on a custom Docker network, attach the Parchment services with an override file in the Parchment directory (where parchment/docker-compose.yml lives). Create parchment/docker-compose.override.yml:

services:
  server:
    networks: [default, your_proxy_network]
  web:
    networks: [default, your_proxy_network]

networks:
  your_proxy_network:
    external: true

Replace your_proxy_network with your actual network name. Then run docker compose up -d from your project root (with the include) so the override is applied.

Updating

From the repository directory:

git pull
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

If you use the standalone method above, re-download the compose file if it changed, then run docker compose pull and up -d.

To update images automatically, add Watchtower to your stack; it will pull new image versions and restart the Parchment containers when they change.

Backup

Only the database is stateful. Back it up regularly:

docker exec parchment-db pg_dump -U server_user parchment > backup.sql

Troubleshooting

PostGIS / database:

docker exec -it parchment-db psql -U server_user -d parchment -h localhost -c "SELECT PostGIS_Version();"
docker exec -it parchment-db psql -U server_user -d parchment -h localhost -c "\d bookmarks"