Deployment overview

Placard is meant to feel like Immich-class self-hosting: Docker Compose first, then panels such as Coolify or Dokploy.

Step-by-step commands: install.md. Google Places BYOK: google-apis.md.

The interactive installer is the quickest way to create a fresh Compose instance on Linux, macOS, or Windows. Docker must already be installed and running Linux containers. Both scripts use the same release assets and generate secrets automatically; local-only access is the default. Existing installs, upgrades, NAS panels, HTTPS, and reverse proxies remain managed through Compose and the instructions below.

TargetStatus
Docker Compose + GHCR imagePrimary
Coolify / Dokploy / similarSame Compose file; map HTTPS to the app service on port 3000
NAS / Unraid / CasaOSUse the Compose file and persistent volumes
Reverse proxy (Caddy, Traefik, nginx)Terminate TLS; forward to PLACARD_PORT (default 3000)

Aspire (aspire run) is for local development of the monorepo. Self-hosters never need the Aspire CLI — use the published image and install.md.

What the Compose stack includes

  • app — API + built web UI + MCP at /mcp
  • worker — background jobs (import, enrichment)
  • db — Postgres + PostGIS
  • Volumes — database data, media (photos), modules (uploaded Marketplace zips)

Health: $PUBLIC_URL/api/health.

Environment (high level)

VariableRequiredPurpose
POSTGRES_PASSWORDyesDatabase password
BETTER_AUTH_SECRETyesSession signing (openssl rand -base64 32)
PUBLIC_URLyesExact public origin (auth and links)
PLACARD_PORTnoHost port (default 3000)
GOOGLE_MAPS_API_KEYnoPlaces BYOK — or set in Settings
MCP_ENABLEDnoDefault true
PLACARD_IMAGEnoOverride image tag

Full comments live in example.env / .env.example.

Nextcloud

Run Placard beside Nextcloud (bookmark or External site). A native Nextcloud PHP app is not required and not the v1 path.

Modules on a deployed instance

Uploaded modules land on the modules volume (PLACARD_MODULES_DIR). Keep that volume across upgrades. See creating-modules.md.

Backup

Instance backup (database + media + modules volumes) is documented in Backup and restore. Library Export in Settings is a per-user zip, not a full disaster-recovery backup.

Upgrades

Follow Upgrade for version pinning, Compose and Coolify updates, verification, and recovery after a failed upgrade.