Installation

Introduction

This guide installs PE Community Management with the supported Docker Compose workflow. Compose builds the application images, starts the required services, waits for service dependencies, and exposes the application for first-run setup.

The API container applies pending Prisma migrations before starting the API process. The operator does not start the API, worker, or web application separately.

What this installation creates

The stack separates browser traffic, application work, persistent records, queued work, and uploaded files. See Architecture for deeper service and data-flow detail.

Before you begin

Use a host that can run Docker Engine with the Docker Compose plugin and has access to the project files. No specific host operating-system version is required.

• Confirm sufficient memory and disk capacity for image builds, running services, PostgreSQL growth, logs, and uploaded media.
• Reserve the host HTTP port configured by HTTP_PORT. PostgreSQL, Redis, API, and web remain internal in this Compose file.
• A domain is optional for the current HTTP workflow. A public installation should use a reviewed TLS-terminating proxy; detailed HTTPS guidance remains outside this validated baseline.
• Allow outbound access needed to fetch container images and packages during image builds. SMTP is needed only for email-dependent features, not for first-run setup.

docker --version
docker compose version

Resource planning

Image builds temporarily use more memory, CPU, and disk than an idle stack. A constrained test host may complete a build with swap enabled, but builds and concurrent services can become slow or unstable; this is not a recommended sustained deployment size.

Plan additional capacity for active users, media uploads, database growth, email and automation queues, backups, and image layers. No supported sizing matrix is available, so monitor the real workload and retain free storage for recovery operations.

Prepare the environment

Work from the project directory and create a private `.env` from the supplied example. Open it with your preferred editor and review Environment variables before starting the stack.

Replace placeholders, generate independent security secrets, select the public origin and host port, and confirm whether environment-based SMTP is required. The current Compose workflow uses a persistent local uploads volume rather than an S3 or MinIO service.

cp .env.example .env

Start the platform

Run the Compose command from the project directory. `-f` selects the deployment file, `-d` starts containers in the background, and `--build` builds the application images before startup.

PostgreSQL and Redis start first and expose health checks. The API waits for both, applies pending migrations, starts, and reports its own health. The web waits for the API health check, and Caddy then routes the configured host port to the stack.

docker compose -f docker-compose.prod.yml up -d --build

Verify the services

Inspect service state before opening setup. PostgreSQL, Redis, and API have health checks; web and worker do not expose health checks in the current Compose file, so use their status and recent logs.

Look for completed migrations, the API listening on port 4000, the web server listening on port 3000, a running worker, and no repeated restart loop. Investigate recurring errors rather than treating container creation as successful verification.

docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs --tail=100 api
docker compose -f docker-compose.prod.yml logs --tail=100 web
docker compose -f docker-compose.prod.yml logs --tail=100 worker

Complete initialization

Open the URL represented by WEB_ORIGIN and HTTP_PORT. An empty installation routes to /setup. Complete First-run setup once, then sign in at /login with the new Owner account. Do not run the demo seed for a real community; it is reserved for development, testing, and demonstration.

Protect persistent data

PostgreSQL records live in `postgres_data`, uploaded avatars and attachments live in `uploads_data`, and Redis append-only data lives in `redis_data`. Caddy also has configuration and data volumes. The Compose project name prefixes these resources.

• `docker compose down` stops and removes containers while retaining named volumes.
• `docker compose down -v` removes the project’s named volumes and can destroy the database and uploaded files.
• `prisma migrate reset` recreates the database and is destructive.
• Changing COMPOSE_PROJECT_NAME can connect the stack to a different set of named volumes, making existing data appear missing.
• Changing database credentials or connection values after initialization requires coordinated database and application changes.

Common installation issues

• Port already in use: change HTTP_PORT or stop the process already bound to that host port.
• Build exits or stalls: review available memory, swap, disk space, and package or image download access.
• API waits or restarts: verify POSTGRES_PASSWORD and inspect PostgreSQL health and migration logs.
• Worker cannot process jobs: confirm Redis is healthy and the worker uses the same internal REDIS_URL as the API.
• Browser requests fail: confirm WEB_ORIGIN and NEXT_PUBLIC_API_URL match the address and same-origin proxy path users actually open.
• Uploads fail: confirm the API and worker can write the mounted uploads volume.
• Setup does not appear: the installation may already contain a community or active privileged membership, or the web server may not reach the setup-status endpoint.

Next steps

• Review Environment variables before changing runtime or build-time values.
• Complete First-run setup and then review Configuration and Security.
• Establish a Backup and restore process before storing important community data.
• Use Docker Compose and Troubleshooting for service-specific operating details.

Current deployment boundary