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.
What is in the image
Section titled “What is in the image”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).
Requirements
Section titled “Requirements”- 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.
Get the image
Section titled “Get the image”Plenary is published to a public registry for linux/amd64 and linux/arm64. No login is needed to pull:
docker pull public.ecr.aws/plenarycms/plenary:v1.5.2Every 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.
Configuration file
Section titled “Configuration file”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:
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.
Secrets
Section titled “Secrets”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:
mkdir -p plenary/secretshead -c 32 /dev/urandom > plenary/secrets/encryption_keyhead -c 32 /dev/urandom > plenary/secrets/jwt_signing_keyopenssl rand -hex 24 > plenary/secrets/setup_tokenThe container runs as the user plenary (uid 100, gid 101), which must be able to read the configuration and secrets:
sudo chown -R 100:101 plenarysudo chmod 700 plenary/secretssudo chmod 600 plenary/secrets/*Back up the encryption key somewhere safe and separate from the database. Never commit these files to source control.
Volumes
Section titled “Volumes”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.
Run with Docker Compose
Section titled “Run with Docker Compose”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:
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_tokenStart it and check that it is healthy:
docker compose up -dcurl 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.
Licensing
Section titled “Licensing”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:
- The
PLENARY_LICENSEenvironment variable, containing the license key itself. - The file at
license.filein the configuration. - 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.
First boot: create the admin user
Section titled “First boot: create the admin user”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.
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
adminrole. Their username is derived from the email address (youforyou@example.com); they can sign in with either. - A site named My Site with the site key
default, usinglocale.defaultandlocale.timezonefrom 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:
- Delete
plenary/secrets/setup_token. With the file gone, the bootstrap endpoint answers404. - 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.
- Follow the Quickstart from step 2 to create your first model.
Upgrades
Section titled “Upgrades”To upgrade, back up first (see Backups), then run the new image and recreate the container:
docker compose pull # or load the new image another waydocker compose up -dPlenary 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.
Backups
Section titled “Backups”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:
docker compose exec -T mongo mongodump --archive --db plenary > plenary-$(date +%F).archiveTo restore, restore the database, the media volume, and the configuration directory from the same backup, then start the container.
Related
Section titled “Related”- Settings: email, SMS, and media storage.
- Licensing: license states and installation.
- Users & Permissions: invite your team.
- Plenary Cloud: the managed alternative.