Install Lunar Paper

Lunar Paper runs on your own server as a set of Docker containers. You do not need the source repository, a public domain or a cloud account. New to Docker? Start with Install Docker.

Choose an installation

For most installations, follow Install with Docker Compose. Paste the commands in the guide to create the configuration and a private environment file, then start Lunar Paper and its supporting services together.

Choose from these guides if you need a different setup:

Guide	Use it for
Docker Compose (recommended)	Most installations
docker run	A quick trial on one computer
Docker Compose with HTTPS	Encrypted access, or a public domain
Arcane	Managing Docker from a web browser

All four use the same containers and volumes, so you can switch later without losing data.

What runs

Service	Role	Reachable from other computers
lunarpaper	The application	Localhost by default; your chosen LAN interface or Caddy when configured
postgres	Official PostgreSQL 17 hosting Platform and Intake	No
redis	Sessions and queues	No
seaweedfs	File storage	No
caddy	HTTPS (optional)	Yes, ports 80 and 443

PostgreSQL and Redis are not reachable from the host, only from Lunar Paper itself. Redis is required, and so is SeaweedFS.

Versions

These installation guides target 0.8.1, hosted in lunarpaper/lunarpaper. Application images will be published to GitHub Container Registry as ghcr.io/lunarpaper/platform:0.8.1. Set LUNAR_PAPER_VERSION=0.8.1 in .env; check GitHub Releases for availability before pulling.

PostgreSQL uses the official postgres:17-alpine image, versioned independently. Lunar Paper’s init files and migrations ship inside the platform image. On first use, unlock the web setup with SETUP_KEY and explicitly initialize the empty databases. Existing installations use the protected upgrade flow.

For later upgrades, change LUNAR_PAPER_VERSION, preserve your configuration and persistent volumes, and update the platform container. PostgreSQL engine updates are separate; do not change its major version as part of a platform update. The separate publishing instance uses ghcr.io/lunarpaper/publisher at the same published version.

Supported engines

Lunar Paper is supported on Docker Engine or Docker Desktop, with Docker Compose v2. Podman, Kubernetes, Docker Swarm and multi-node setups are not supported.

After you install

Once Lunar Paper is running, continue with Getting Started: create your first service.

• Keep your .env file, or the secrets you saved, safe and off the server. See Configuration and secrets.
• Set up and test backups.
• Read Upgrades and rollback before your first upgrade.
• Activate your licence. See Licensing.
• To show published forms and pages to people outside Lunar Paper, set up a publishing instance.