Installation
Install Clearplane with Docker Compose and choose optional Cloud health and error reporting.
Clearplane runs from a release's docker-compose.yml and four published container images. Docker Compose owns installation, updates, and the container lifecycle. Application commands run through the CLI embedded in Core.
Alpha release: The supported target is one Linux Docker host. High availability, multi-host orchestration, rolling upgrades, and supported matched backup and restore are not included.
Host requirements
- Linux on
x86_64orarm64, with Docker Engine and Docker Compose 2.24.0 or newer. - A local Unix Docker socket accessible under the host's permission and SELinux policy.
- At least 4 GiB RAM for Clearplane and 10 GiB free on Docker's data filesystem. Reserve additional memory for other applications on the host.
- Available TCP ports 80 and 443, UDP port 443 for HTTP/3, registry access, and DNS for the hostnames you will publish.
Images include the runtime; the host needs no .NET installation or source build. Operators configure Docker, DNS, firewalls, and host permissions. Publish HTTPS on the same public TCP and UDP port and allow both through the host firewall when using HTTP/3.
Download the release
Download docker-compose.yml from the Clearplane release into a deployment directory. Run every Compose command below from that directory.
During the private alpha, sign in to GitHub Container Registry with an authorized GitHub account and a personal access token with read:packages. Enter the token at the password prompt:
docker login ghcr.io -u <github-username>
An optional .env file can set CLEARPLANE_IMAGE_TAG to another published version. For a nondefault local Docker socket, change the host side of the socket volume in docker-compose.yml. See the environment variable reference.
Configure browser access
The shipped UI and API routes are disabled, and their access control blocks every address. Add these labels to the clearplane-core and clearplane-ui services, in docker-compose.yml itself or in a docker-compose.override.yml beside it, replacing the hostname, email and administrator address:
services:
clearplane-core:
labels:
clearplane.core.acme.email-address: "admin@example.com"
clearplane.core.acme.terms-of-service-agreed: "true"
clearplane.proxy.enabled: "true"
clearplane.proxy.host: "waf.example.com"
clearplane.proxy.access-control.allowed-addresses: "203.0.113.10/32"
clearplane.proxy.certificate.enabled: "true"
clearplane.proxy.redirect.http-to-https: "true"
clearplane-ui:
labels:
clearplane.proxy.enabled: "true"
clearplane.proxy.host: "waf.example.com"
clearplane.proxy.access-control.allowed-addresses: "203.0.113.10/32"
clearplane.proxy.certificate.enabled: "true"
clearplane.proxy.redirect.http-to-https: "true"
The UI and API must share a hostname because the browser calls same-origin /api/ and /api/ws/. The management access control blocks by default; allow your administrator address or a narrow VPN CIDR, separating several with spaces. Avoid broad private-network ranges that could also admit application containers.
For HTTP-01 certificates, point the public A/AAAA records at Edge and keep public TCP port 80 reachable for issuance and renewal. See Enable HTTPS for DNS-01 and other certificate options.
All four services run regardless of route exposure. You can enable only the Core route for API access or leave both management routes disabled.
Examples use the shipped service keys. If you rename services, use your keys in commands, overrides, and dependency references. Preserve the canonical clearplane-core, clearplane-edge, clearplane-ui, and clearplane-container-proxy aliases on clearplane-internal.
Start and complete setup
docker compose config --quiet &&
docker compose pull &&
docker compose up -d --wait
Once the management hostname has trusted HTTPS, issue a setup code:
docker compose exec clearplane-core clearplane installation setup-code
The command prints the setup URL from the UI route's host, here https://waf.example.com/setup. Open it and create the first administrator. Never submit setup codes or passwords over public plaintext HTTP.
After creating the first administrator, browser setup offers authenticator-app MFA. Enroll now or choose Skip for now to continue without MFA. You can enable it later in your account security settings. MFA is also optional for the first administrator created through the terminal. Users added later still default to requiring MFA, which an administrator can change per user.
Setup offers Cloud integration, off by default. Enabling it connects this installation to Clearplane Cloud and reveals separate feature choices:
- Health reporting sends host and service health. It is off by default.
- Error reporting sends bounded diagnostic metadata. It is off by default.
- WAF ruleset updates downloads signed WAF rulesets from Cloud and activates new releases in Detection. It is off by default. Without active compatible rulesets, the WAF has no rules to inspect.
- Cloud Protection is coming later for Community, Business and Enterprise and remains unavailable.
You can complete setup with Cloud off and change these choices later in System → Settings → Cloud. Local protection works without Cloud.
Every route starts under the Global WAF policy Default WAF in Detection, which records findings without blocking; the shipped management routes keep their own Management-profile policies. Until a WAF ruleset is active, the dashboard warns that nothing is inspected. Clear the warning in one of three ways: turn on Cloud integration and WAF ruleset updates, publish a custom ruleset, or set Default WAF and every other enabled WAF policy to Off. See WAF policies.
Read the Cloud data and consent details before enabling reports.
To complete setup through an attached terminal when the UI route is disabled:
docker compose exec clearplane-core clearplane administrator create
Terminal-only setup leaves Cloud integration, health reporting, error reporting and WAF ruleset updates off. Operators with settings write permission can change them later in the UI or through the authenticated Cloud configuration API.
Operate and update
| Task | Command |
|---|---|
| Container status | docker compose ps |
| Recent Core logs | docker compose logs --tail 200 clearplane-core |
| Follow Edge logs | docker compose logs --follow clearplane-edge |
| Stop and keep containers | docker compose stop |
| Start or apply changes | docker compose up -d --wait |
| Restart existing containers | docker compose restart |
| Remove containers and project networks, keeping named volumes | docker compose down |
For an update, replace docker-compose.yml with the newer release's file, preserve your overrides, and review any CLEARPLANE_IMAGE_TAG override. Then run:
docker compose pull && docker compose up -d --wait
An image-tag change does not provide database rollback; a version that cannot recognize the stored migration history refuses startup. Use up -d --wait to apply image or Compose changes; restart only restarts existing containers.
Alpha upgrades: alpha releases migrate databases but never older secrets, settings, labels or other persisted state. When a release changes them, Core refuses the old state: remove it with docker compose down --volumes, start again with docker compose up -d --wait and complete setup. Upgrading from 1.0.0-alpha8 or earlier requires this, because 1.0.0-alpha9 renames labels, settings and the WAF ruleset format.
Edge retains its previous valid configuration while Core is unavailable.
The CLI reference covers installation status, setup, administrator recovery, ban removal, database maintenance, and secret rotation. Operations covers application monitoring and troubleshooting.
Data and removal
The shipped volumes are:
| Volume | Contents |
|---|---|
clearplane-core-data |
Application database, IP-data database (database/ip-data.db: bans, IP filters, blocked addresses and GeoIP country data; created automatically), data-protection keys, administrator signing key, internal CA/private key, Core identity, and generation manifest. |
clearplane-edge-data |
Stored certificates and password, CA copy, and Edge identity; Edge mounts it read-only. |
clearplane-ui-data |
UI CA copy and identity; UI mounts it read-only. |
clearplane-container-proxy-data |
ContainerProxy CA copy and identity; ContainerProxy mounts it read-only. |
clearplane-analytics |
Analytics database and ingestion checkpoints. |
clearplane-logs |
Raw application/audit logs and Core's indexed log catalog. |
clearplane-cache |
Disposable Edge response cache and the GeoIP cache file that lets Edge restart without Core. |
Core requires all six durable mounts. Preserve them together as one matched generation. Partial state after interrupted provisioning or migration requires diagnosis and recovery; startup never treats remaining artifacts as disposable. See database maintenance for the validation rules.
The shipped networks and volumes have fixed names; changing the directory or Compose project name does not isolate a second installation on the same host.
docker compose down --volumes permanently removes all seven named volumes, including databases, keys, certificates, analytics, logs, and cache. Use it only when complete deletion is intended.