Skip to content

Self-Hosted Install

A self-hosted Plenary installation is one Docker container plus a MongoDB database that you run. The container holds everything else: the API, the admin console, the media worker, and a web server. Use this when you need Plenary on your own infrastructure; if you would rather not run servers, use Plenary Cloud.

The Plenary image runs four things in one container:

Process Role
plenaryd The API server. Listens on port 8080 inside the container.
artifexd The media worker. Generates image variants and video posters.
Console The admin web app, served as static files.
Caddy The web server. Listens on port 80 and routes requests to the others.

Caddy routes requests on port 80 like this:

Path Goes to
/ Redirects to /cms
/cms and below The admin console
/api/ and below plenaryd
/media/ and below Media files on disk, or plenaryd when a file is not on disk

The container serves plain HTTP. Put it behind your own reverse proxy or load balancer to terminate TLS.

The container’s entrypoint starts all processes and exits as soon as any one of them exits. It does not restart them itself, so run the container with a restart policy (restart: unless-stopped in Docker Compose, or your orchestrator’s equivalent).

  • A Docker host (or any container platform, such as ECS or Kubernetes).
  • MongoDB, reachable from the container. A standalone server works; a replica set is not required.
  • A hostname for the instance, such as cms.example.com, and a reverse proxy or load balancer that terminates TLS for it.
  • Optionally, a Plenary license bound to that hostname. Without one the instance runs on the Free plan: one site, no forms, no single sign-on, no GraphQL API. See Licensing.

Plenary is published to a public registry for linux/amd64 and linux/arm64. No login is needed to pull:

Terminal window
docker pull public.ecr.aws/plenarycms/plenary:v1.5.2

Every release has an immutable tag, v followed by its version. The major version is also a moving tag (public.ecr.aws/plenarycms/plenary:1) that follows the newest compatible release. There is no latest tag: a licensed instance that pulled a release newer than its license’s update window would drop to the Free plan, so pin a version and upgrade deliberately. The examples on this page use v1.5.2; replace it with the release you are installing.

Plenary reads one YAML file. Inside the container its default path is /etc/plenary/plenary.yaml; set the PLENARY_CONFIG environment variable to use a different path. Both plenaryd and artifexd read the same file.

Any ${VAR_NAME} in the file is replaced with that environment variable’s value when the file is loaded. If a referenced variable is not set, Plenary refuses to start and names the missing variables. Use this to keep the database password out of the file.

A complete starting configuration:

plenary/plenary.yaml
server:
bind_address: "0.0.0.0"
port: 8080
public_url: "https://cms.example.com"
mongodb:
url: "${PLENARY_MONGODB_URL}"
auth:
jwt:
issuer: "plenary"
secrets:
encryption_key_file: "/etc/plenary/secrets/encryption_key"
jwt_signing_key_file: "/etc/plenary/secrets/jwt_signing_key"
license:
file: "/etc/plenary/secrets/license"
storage:
local_data_dir: "/var/lib/plenary"
temp_dir: "/tmp/plenary"
bootstrap:
setup_token_file: "/etc/plenary/secrets/setup_token"
allow_initial_setup: false
locale:
default: "en-us"
timezone: "UTC"
logging:
level: "info"
format: "json"

The settings you are most likely to change:

Key Default What it does
server.public_url none The public URL of the instance, without a trailing slash. Used for token audiences, CORS for the console, and license host matching. Required.
server.bind_address 0.0.0.0 Address plenaryd listens on inside the container.
server.port 8080 Port plenaryd listens on inside the container. Keep 8080: the bundled Caddy forwards /api/ to localhost:8080.
mongodb.url none MongoDB connection string. The database name is the URL path; with no path, Plenary uses the database plenary.
auth.jwt.issuer none Issuer name stamped into console session tokens.
auth.jwt.access_token_ttl 15m Lifetime of a console access token.
auth.jwt.refresh_token_ttl 720h (30 days) Lifetime of a console refresh token.
secrets.encryption_key_file none Path to the encryption key. See Secrets. Required.
secrets.jwt_signing_key_file none Path to the session signing key. Required.
license.file none Path to a license file. See Licensing.
storage.local_data_dir none Where uploaded media is stored when media uses local storage. Keep /var/lib/plenary: that is the directory the bundled Caddy serves /media/ files from.
storage.temp_dir none Scratch space for uploads and processing.
bootstrap.setup_token_file none Path to the one-time token that authorizes creating the first admin.
locale.default none Default locale for new sites, such as en-us.
locale.timezone none Default IANA timezone for new sites, such as UTC or America/Denver.
logging.level info debug, info, warn, or error.
logging.format text json or text.
content.schedule_sweep_interval 1m How often scheduled publish and unpublish times are checked.
webhooks.delivery concurrent concurrent, or ordered to deliver webhooks one at a time, oldest first.
webhooks.delivery_retention 720h (30 days) How long webhook delivery records are kept. 0 keeps them forever.
error_reporting.sentry_dsn none Send errors to a Sentry project. Leave unset to turn off.

Email sending, SMS sending, and media storage (local disk or Amazon S3) are not configured in this file. An admin sets them in the console under Admin Settings → Global Settings after first boot. See Settings.

Plenary needs two key files before it starts. Both plenaryd and artifexd exit at startup if either file is missing.

File Used for If you lose it
Encryption key (secrets.encryption_key_file) Encrypting credentials stored in the database, such as email, SMS, and S3 credentials entered in Global Settings. Those stored credentials cannot be decrypted. You must enter them again.
JWT signing key (secrets.jwt_signing_key_file) Signing console session tokens. Everyone is signed out. Nothing else is lost.

Each key is 32 random bytes. Generate them, together with a setup token for first boot, in a plenary/secrets directory next to your Compose file:

Terminal window
mkdir -p plenary/secrets
head -c 32 /dev/urandom > plenary/secrets/encryption_key
head -c 32 /dev/urandom > plenary/secrets/jwt_signing_key
openssl rand -hex 24 > plenary/secrets/setup_token

The container runs as the user plenary (uid 100, gid 101), which must be able to read the configuration and secrets:

Terminal window
sudo chown -R 100:101 plenary
sudo chmod 700 plenary/secrets
sudo chmod 600 plenary/secrets/*

Back up the encryption key somewhere safe and separate from the database. Never commit these files to source control.

Mount two locations:

Container path Contents Persist it?
/etc/plenary plenary.yaml and the secrets/ directory. Can be mounted read-only. Yes. Back it up.
/var/lib/plenary Uploaded media and generated variants, when media uses local storage. Yes. Back it up.

If you switch media storage to Amazon S3 in Global Settings, new uploads go to your bucket instead, but keep the volume for anything already stored on disk.

This Compose file runs MongoDB and Plenary together and publishes Plenary on port 8080 of the host’s loopback interface, for a reverse proxy on the same host to forward to:

docker-compose.yml
services:
mongo:
image: mongo:8
restart: unless-stopped
volumes:
- mongo-data:/data/db
plenary:
image: public.ecr.aws/plenarycms/plenary:v1.5.2
restart: unless-stopped
depends_on:
- mongo
ports:
- "127.0.0.1:8080:80"
environment:
PLENARY_MONGODB_URL: "mongodb://mongo:27017/plenary"
volumes:
- ./plenary:/etc/plenary:ro
- plenary-media:/var/lib/plenary
volumes:
mongo-data:
plenary-media:

Your directory should look like this:

.
├── docker-compose.yml
└── plenary
├── plenary.yaml
└── secrets
├── encryption_key
├── jwt_signing_key
├── license
└── setup_token

Start it and check that it is healthy:

Terminal window
docker compose up -d
curl http://127.0.0.1:8080/api/v1/health
{ "status": "ok", "database": "ok", "version": "1.3.0", "edition": "on-prem", "license": "ok", "tier": "full" }

status is ok when the database answers, and degraded (with HTTP 503) when it does not. license reports the license state and tier whether the instance is on the Free plan (free) or licensed (full); neither affects the HTTP status. Use this endpoint for your load balancer’s health check.

Then point your reverse proxy at 127.0.0.1:8080 for your hostname, terminating TLS.

A self-hosted instance runs without a license on the Free plan: one site, no forms, and no single sign-on. Everything else, including creating as many users as you need, works. A license lifts the three limits. See The Free plan for exactly what is refused and how.

Get a license:

  • Evaluation. Sign up at plenarycms.com/signup and choose Docker / Self-hosted in the last step. You enter the hostname the instance will run at, and receive an evaluation license key.
  • Purchased. From On-prem licenses in the account portal at plenarycms.com/account.

A license is bound to one or more hostnames. Plenary compares them with the host in server.public_url. A license for cms.example.com only works when public_url is https://cms.example.com. One wildcard label is allowed, such as *.staging.example.com.

Plenary looks for the license in three places, in this order, and uses the first one it finds:

  1. The PLENARY_LICENSE environment variable, containing the license key itself.
  2. The file at license.file in the configuration.
  3. A license an admin installed in the console under Admin Settings → License.

Sources 1 and 2 are read at startup, so changing them requires a restart. A license installed in the console takes effect immediately. A new install can start on the Free plan and have its license installed in the console once the admin signs in, or carry it from the first boot through the environment variable or the file.

When public_url points at localhost or 127.0.0.1, the license is not enforced, so you can try Plenary locally without one.

See Licensing for license states, error codes, and update windows.

A new instance has no users. Create the first admin, and the first site, with one call to the bootstrap endpoint. It is authorized by the setup token from bootstrap.setup_token_file, sent in the X-Setup-Token header, and it works only once: after any user exists it returns 409.

Terminal window
curl -X POST https://cms.example.com/api/v1/setup/bootstrap \
-H "Content-Type: application/json" \
-H "X-Setup-Token: $(cat plenary/secrets/setup_token)" \
-d '{
"admin": {
"email": "you@example.com",
"password": "Choose-a-strong-passw0rd",
"first_name": "Ada",
"last_name": "Lovelace"
},
"site": { "name": "My Site" }
}'
{ "status": "ok" }

This creates:

  • An admin user with the admin role. Their username is derived from the email address (you for you@example.com); they can sign in with either.
  • A site named My Site with the site key default, using locale.default and locale.timezone from the configuration.
Field Required Notes
admin.email Yes The admin’s email address.
admin.password Yes At least 8 characters, with an upper-case letter, a lower-case letter, and a digit.
admin.first_name No
admin.last_name No
admin.display_name No Defaults to a name derived from first and last name.
site.name Yes Display name of the first site.

Errors from this endpoint:

Status Code Meaning
403 invalid_setup_token The X-Setup-Token header does not match the token file.
404 not_found The token file named by bootstrap.setup_token_file is missing or empty.
409 already_bootstrapped A user already exists.
422 invalid_email, password_too_short, password_missing_uppercase, password_missing_lowercase, password_missing_digit, site_name_required The request body is invalid.

Now sign in to the console at https://cms.example.com/cms. Then:

  1. Delete plenary/secrets/setup_token. With the file gone, the bootstrap endpoint answers 404.
  2. Open Admin Settings → Global Settings and configure email sending, so Plenary can send invitations and password resets. Set up SMS and S3 media storage there too if you need them.
  3. Follow the Quickstart from step 2 to create your first model.

To upgrade, back up first (see Backups), then run the new image and recreate the container:

Terminal window
docker compose pull # or load the new image another way
docker compose up -d

Plenary applies any database changes a release needs automatically when it starts. Each change runs once and is recorded in the database. There is no separate migration step.

A license can limit which releases it covers. If you start a release newer than your license allows, the instance runs on the Free plan and /api/v1/health reports "license": "update_window_exceeded", "tier": "free". Go back to the previous image, or install a renewed license. Pinning the vX.Y.Z tag rather than the moving major tag keeps this from happening by surprise. See Licensing.

Back up three things, ideally at the same time:

What How
The MongoDB database mongodump, or your MongoDB host’s snapshot feature. All content, models, users, settings, and revision history live here.
Media files The volume mounted at /var/lib/plenary, if media uses local storage. If it uses S3, back up the bucket instead.
Configuration and secrets The directory mounted at /etc/plenary. Without the encryption key, credentials stored in the database cannot be decrypted.

For example, with the Compose file above:

Terminal window
docker compose exec -T mongo mongodump --archive --db plenary > plenary-$(date +%F).archive

To restore, restore the database, the media volume, and the configuration directory from the same backup, then start the container.