User docs/Administrator guide

Planned installation (not released)

PeltyCMS is not released yet. There is no public download, image or installer today. This page describes how installation is planned to work at release, and the details may change.

At release, PeltyCMS is planned to be one server binary, pelty-server, plus a PostgreSQL 16+ database. The binary serves the API, the built frontend and these docs, runs the database migrations on start and runs the background scheduler, so no separate cron or worker is needed.

#Requirements

• PostgreSQL 16 or newer.
• A domain with TLS in front of PeltyCMS (a reverse proxy such as nginx or Caddy). The server listens on plain HTTP.
• For building from source: Rust with the wasm32-wasip2 target, Node.js 20+ with pnpm, and GNU make.

#Docker Compose (planned)

The repository ships a Dockerfile and a docker-compose.yml. Put the secrets in a .env file next to the compose file (never commit it), then start it and create the first admin:

docker compose up -d
docker compose run --rm app admin create [email protected]

# UNVERIFIED: statically reviewed, never run (no Docker on the dev box).
# Put secrets in a .env file next to this file (never commit it):
#   POSTGRES_PASSWORD=<long random>
#   PELTY_ENCRYPTION_KEY=<32-byte key, base64>   # encrypts server API keys / gateway secrets
#   PELTY_PUBLIC_URL=https://billing.example.com
# Optional: PELTY_SMTP_URL, PELTY_MAIL_FROM, PELTY_COOKIE_SECURE (default true here),
#   PELTY_AUTH_RATE_PER_MINUTE, PELTY_PROVISION_ALLOW_LINK_LOCAL (keep unset).
# First admin: docker compose run --rm app admin create [email protected]
services:
  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: pelty
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: peltycms
    volumes: [pgdata:/var/lib/postgresql/data]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U pelty -d peltycms"]
      interval: 5s
      retries: 10
  app:
    build: .
    restart: unless-stopped
    depends_on:
      db: { condition: service_healthy }
    environment:
      DATABASE_URL: postgres://pelty:${POSTGRES_PASSWORD}@db:5432/peltycms
      PELTY_ENCRYPTION_KEY: ${PELTY_ENCRYPTION_KEY:-}
      PELTY_PUBLIC_URL: ${PELTY_PUBLIC_URL:-http://localhost:8080}
      PELTY_SMTP_URL: ${PELTY_SMTP_URL:-}
      PELTY_MAIL_FROM: ${PELTY_MAIL_FROM:-}
      PELTY_COOKIE_SECURE: ${PELTY_COOKIE_SECURE:-true}   # set false only for plain-HTTP local testing
    read_only: true
    tmpfs: [/tmp]
    security_opt: ["no-new-privileges:true"]
    cap_drop: [ALL]
    # Bind to localhost; put a TLS reverse proxy in front.
    ports: ["127.0.0.1:8080:8080"]
volumes:
  pgdata:

The image runs pelty-server serve, listens on 0.0.0.0:8080 (PELTY_BIND), and has a health check on /healthz. The compose file binds it to 127.0.0.1:8080 so only your reverse proxy can reach it.

#From source

make build      # frontend, server binary, addon zips and these docs
./target/release/pelty-server migrate
./target/release/pelty-server admin create [email protected]
./target/release/pelty-server serve

admin create reads the password from PELTY_ADMIN_PASSWORD or the first line of standard input. make help lists every target; see CLI for all commands, including the WHMCS, Blesta and Paymenter importers.

#Required configuration

Only a few environment variables are needed to run in production:

PELTY_ENCRYPTION_KEY encrypts stored secrets (server API keys, gateway and addon secrets). Keep it safe and keep it the same across restarts: secrets saved with one key cannot be read with another.

Everything else (company details, currencies, mail, gateways, tax, security policy) is configured in the admin area and stored in the database. Continue with First-run setup.

#All environment variables

Generated from the code; the developer reference Configuration also shows which file reads each variable.