- Overview
- Reference Guide
- Setup & Architecture
- Release Notes
- Workflow
- API Reference
- Integration Guide
- Discovery Agent Setup Guide
Docker
A CertSecure Docker deployment is upgraded by unpacking the new release bundle into a new directory, copying the environment file and realm configuration from the current deployment, and running the installation script from the new directory. The upgrade does not require internet access.
All CertSecure data is kept in Docker named volumes, and the Docker Compose project name is always certsecure. The containers of the new release therefore attach to the existing volumes, and all certificates, users, realms and settings are kept.
Table 1: Volumes Kept During an Upgrade
| Volume | Contents |
|---|---|
| certsecure_mongo-data | All application data: inventory, enrollments, users, settings and sessions. |
| certsecure_keycloak-data | Keycloak database: realm, users, clients and identity providers. |
| certsecure_backend-logs | Rotating application and connector logs. |
| certsecure_backend-cache | Authentication token cache. |
| certsecure_mcp-logs | MCP server logs. Present only when the MCP server is enabled. |
An upgrade has four stages:
- Prerequisites for an Upgrade: confirm the release notes, maintenance window, bundle, disk space and environment file.
- Prepare for the Upgrade: record the current state, tag the current images and back up the data.
- Upgrade: unpack the new bundle, copy the configuration and run the installation.
- Verify the Upgrade and Complete Post-Upgrade Tasks: check the new release and clean up.
If something goes wrong, see Roll Back an Upgrade and Troubleshoot the Upgrade.
Important: Do not run docker compose down -v or ./teardown-docker.sh --volumes at any point during an upgrade. They delete all CertSecure data.
Note: Commands in this section are shown for a Linux host. For the Windows equivalents, see Upgrade on a Windows Host.
Prerequisites for an Upgrade
Before you upgrade, confirm each of the following.
Table 2: Upgrade Prerequisites
| Prerequisite | Description |
|---|---|
| Release notes | Read the release notes for the new release. They state whether a database migration or other additional step is required. |
| Maintenance window | CertSecure is unavailable from the time the current containers stop until the new containers are healthy, typically 15 to 30 minutes including the backup. |
| Release bundle | The new bundle, CertSecure-Docker-<NEW_VERSION>.tar.gz, is on the host and its checksum has been verified (see Prepare the Installation Files in the Docker installation guide). |
| Disk space | At least 10 GB free on the Docker data file system, plus space for the volume backups. |
| Environment file | The .env file of the current deployment is available. It contains generated secrets that the new release requires. |
| Kernel | The host kernel is below 6.19, or 7.0.14 or later. To check, run docker info --format '{{.KernelVersion}}'. |
| Earlier releases | If the current deployment is from a release that did not use MongoDB authentication, read Upgrade from an Earlier Release before you stop the containers. |
Prepare for the Upgrade
The following steps record the current state for comparison, preserve the current images for roll back, and back up the data while no container is writing to it.
Step 1: Set the Bundle Directories
Set shell variables for the current and new bundle directories. They are used in the rest of this section. For example:
OLD=/opt/certsecure/CertSecure-Docker-<CURRENT_VERSION>
NEW=/opt/certsecure/CertSecure-Docker-<NEW_VERSION>Step 2: Record the Current State
curl -fk https://<API_HOSTNAME>/version
docker images | grep certsecure
cd $OLD/docker && docker compose ps
grep -E 'CERTSECURE_SSL|CERTSECURE_AGENTS_DIR|CERTSECURE_MCP_ENABLED' .envNote the version, whether the MCP server is enabled, and where the TLS certificate and agent installers are stored. Also note the certificate count displayed on the dashboard, to compare after the upgrade.
Step 3: Check the New Bundle
Confirm the new bundle is the expected release by displaying its manifest:
tar -xzOf CertSecure-Docker-<NEW_VERSION>.tar.gz \
CertSecure-Docker-<NEW_VERSION>/BUNDLE-MANIFEST.txtStep 4: Tag the Current Images
Tag the current images so that they can be used for roll back:
docker tag certsecure-backend:latest certsecure-backend:pre-upgrade
docker tag certsecure-keycloak:latest certsecure-keycloak:pre-upgrade
docker tag certsecure-mcp:latest certsecure-mcp:pre-upgrade # if the MCP server is enabledImportant: Tag the images before you run the installation script of the new release, which loads the new images and moves the latest tag. If the new release has the same version number as the current release, loading it also moves the version tag.
Step 5: Stop the Current Containers
cd $OLD/docker
docker compose downNote: If the MCP server is enabled, run COMPOSE_PROFILES=mcp docker compose down instead.
Step 6: Back Up the Data and Configuration
Back up the MongoDB and Keycloak volumes and the configuration files:
mkdir -p ~/certsecure-backup
docker run --rm --entrypoint tar \
-v certsecure_mongo-data:/data -v ~/certsecure-backup:/backup mongo:8.0.21 \
-czf /backup/mongo-data-$(date +%F).tar.gz -C /data .
docker run --rm --entrypoint tar \
-v certsecure_keycloak-data:/data -v ~/certsecure-backup:/backup mongo:8.0.21 \
-czf /backup/keycloak-data-$(date +%F).tar.gz -C /data .
cp $OLD/docker/.env $OLD/docker/deploy/server.yaml ~/certsecure-backup/
ls -lh ~/certsecure-backupTip: Confirm that each archive is a plausible size, not a few kilobytes, before you continue. The backups are required to roll back an upgrade that changes the database.
Upgrade
The new release is unpacked beside the current one, so that the current release remains available for roll back. The web UI and the agent installers are served from the directory the installation script runs in, so the script must run from the new bundle directory.
Step 1: Unpack the New Bundle
cd /opt/certsecure
tar -xzf CertSecure-Docker-<NEW_VERSION>.tar.gzImportant: Do not unpack the new bundle into the current bundle directory, and do not copy the new images.tar.gz into the current bundle directory. Keep the current bundle directory unchanged until the upgrade is accepted.
Step 2: Copy the Configuration
Copy the configuration from the current deployment to the new one:
-
Copy the environment file and restrict its permissions:
cp $OLD/docker/.env $NEW/docker/.env chmod 600 $NEW/docker/.env -
Copy the realm configuration and the render state:
cp $OLD/docker/deploy/server.yaml $NEW/docker/deploy/server.yaml cp $OLD/docker/deploy/.render-state.json $NEW/docker/deploy/ 2>/dev/null || true -
If CERTSECURE_SSL_CERT and CERTSECURE_SSL_KEY use paths inside the current bundle, such as the default ./certs-local/, copy the certificate directory:
cp -r $OLD/docker/certs-local $NEW/docker/ -
If you added signed agent installers to the current bundle, and CERTSECURE_AGENTS_DIR is not set, copy them:
cp -r $OLD/bin/Agents/Signed/. $NEW/bin/Agents/Signed/
The table below explains why each file is copied:
Table 3: Files Copied During an Upgrade
| File | Description |
|---|---|
| docker/.env | Deployment settings and the generated Keycloak client secret, Keycloak service-account password, application secret key and MongoDB password. Without it, the new release generates new secrets that the existing Keycloak and MongoDB do not recognize, and the installation stops. |
| docker/deploy/server.yaml | Realms added or changed on the Manage Realms page. Without it, the realm configuration is rebuilt from .env and realms added in the web UI are lost. |
| docker/deploy/.render-state.json | Records the realm Keycloak imported, so the installation can confirm it has not changed. Optional. |
| docker/certs-local/ | Required only when the TLS certificate is stored inside the bundle. Without it, a new self-signed certificate is generated and browsers display a warning again. |
Tip: Store the TLS certificate and the agent installers at absolute paths outside the bundle, for example under /opt/certsecure. Future upgrades then require copying only .env, server.yaml and .render-state.json.
Step 3: Run the Installation Script
Run the installation script from the new bundle directory:
cd $NEW/docker
./deploy-docker.shNote: On a host below the minimum specification, the installation script asks whether to continue. For an unattended upgrade on such a host, set CERTSECURE_ACK_UNDERSIZED=1 in .env.
Step 4: Review the Script Output
Confirm that the output includes the following:
- [ ok ] Image and bundle are the same release.
- An agent installer count that is not zero.
- refreshed server.yaml (preserved realm(s): ...), listing your realms.
- No message about generating new secrets. If the script reports that it generated secrets, .env was not copied; stop and repeat Step 2.
- [ ok ] CertSecure stack is up.
Verify the Upgrade
-
Confirm that the containers are healthy and that the volumes are the same as before the upgrade:
docker compose ps docker volume ls | grep certsecure -
Confirm that the API reports the new version:
curl -fk https://<API_HOSTNAME>/version -
Confirm that the agent installers are available. The command must return HTTP status 200:
curl -fkI https://<API_HOSTNAME>/connector/download-connector/discovery_agent_windows -
If the MCP server is enabled, confirm that it is healthy and returns 401:
COMPOSE_PROFILES=mcp docker compose ps mcp curl -k -s -o /dev/null -w '%{http_code}\n' https://<API_HOSTNAME>/mcp - In a browser, sign in to CertSecure, including through single sign-on if it is configured.
- Confirm that the certificate count on the dashboard matches the count recorded before the upgrade, and open an inventory list and a report.
- Confirm that agents are reporting in and their last contact time is updating.
Note: No browser certificate warning needs to be accepted again unless the host names or the certificate changed.
Complete Post-Upgrade Tasks
Run Database Migrations
Database migrations are not run by the installation script. Run a migration only if the release notes require one.
-
From the new bundle's docker directory, run the migration in the backend container:
docker compose exec backend python DB_Migrator.py - Repeat the checks in Verify the Upgrade.
Remove the Previous Release
Keep the previous bundle directory, the pre-upgrade image tags and the backups until the new release has run without issues for an agreed period. Then:
-
Remove the pre-upgrade image tags and unused image layers:
docker rmi certsecure-backend:pre-upgrade certsecure-keycloak:pre-upgrade docker image prune -
Delete the previous bundle directory:
rm -rf $OLD - Keep or delete the backups according to your retention policy.
Roll Back an Upgrade
An upgrade can be rolled back by running the installation script from the previous bundle directory. The previous bundle reloads its own images and attaches to the same volumes. Rolling back the application does not roll back the data; if the new release changed the database, restore the backups as well.
-
Stop the containers of the new release. If the MCP server is enabled, run COMPOSE_PROFILES=mcp docker compose down instead.
cd $NEW/docker docker compose down -
If the release notes state that the new release changes the database, or a migration was run, restore the volumes from the backup:
docker run --rm --entrypoint sh \ -v certsecure_mongo-data:/data -v ~/certsecure-backup:/backup mongo:8.0.21 \ -c 'rm -rf /data/* && tar -xzf /backup/mongo-data-<DATE>.tar.gz -C /data' docker run --rm --entrypoint sh \ -v certsecure_keycloak-data:/data -v ~/certsecure-backup:/backup mongo:8.0.21 \ -c 'rm -rf /data/* && tar -xzf /backup/keycloak-data-<DATE>.tar.gz -C /data' -
Run the installation script from the previous bundle directory:
cd $OLD/docker ./deploy-docker.shIf the previous bundle's images.tar.gz is no longer available, add CERTSECURE_IMAGE_TAG=pre-upgrade to $OLD/docker/.env before you run the script, to use the images tagged in Prepare for the Upgrade.
- Repeat the checks in Verify the Upgrade and confirm that the previous version is reported.
Upgrade from an Earlier Release
This section applies when the current deployment is from an earlier release of the CertSecure Docker bundle. The upgrade always uses the scripts of the new release, so limitations of the earlier scripts do not apply.
Enable MongoDB Authentication on an Existing Database
Current releases run the bundled MongoDB with authentication. MongoDB creates its user only when it initializes an empty data volume, so a volume created by a release without authentication has no user. The installation detects this and stops without making changes. To keep the existing data, create the user before you run the installation.
-
Complete steps 1 and 2 of Upgrade, then change to the new bundle's docker directory:
cd $NEW/docker -
Start only the MongoDB container. It starts without authentication because the volume has no user:
docker compose up -d mongo -
Create the user. Use a password of letters and digits only, so that it does not need to be encoded in the connection string:
docker exec certsecure-mongo-1 mongosh --quiet --eval \ 'db.getSiblingDB("admin").createUser({user:"certsecure", pwd:"<MONGO_PASSWORD>", roles:[{role:"root",db:"admin"}]})' -
Add the user name and password to .env, so the installation uses them:
printf 'CERTSECURE_MONGO_USER=certsecure\n' >> .env printf 'CERTSECURE_MONGO_PASSWORD=<MONGO_PASSWORD>\n' >> .env -
Continue with step 3 of Upgrade:
./deploy-docker.sh -
Confirm that authentication is enforced. The command must fail with a message that the command requires authentication:
docker exec certsecure-mongo-1 mongosh --quiet --eval 'db.adminCommand({listDatabases:1})'
Note: A healthy MongoDB container does not confirm that authentication is enabled, because its health check uses a command that MongoDB answers without credentials.
If the existing data is not required, for example on a test deployment, run ./teardown-docker.sh --volumes instead, which deletes all data, then run the installation normally.
Move the Agent Installers and Certificate Outside the Bundle
Earlier releases stored the agent installers and the certificate inside the bundle by default. Moving them outside the bundle means future upgrades do not copy them (see Configure Agents and Connectors in the Docker installation guide). Earlier deployments can also have an unused certsecure_agent-bin volume. After the upgrade is accepted, remove it with docker volume rm certsecure_agent-bin.
New Installation Checks
| Check | Effect on an upgrade |
|---|---|
| Kernel | The installation stops on a kernel from 6.19 through 7.0.13. This cannot be overridden. |
| Host specification | Below 16 vCPU, 32 GB memory or 300 GB disk, the installation asks whether to continue. Without a terminal, for example when run by a scheduler, it stops unless CERTSECURE_ACK_UNDERSIZED=1 is set. |
| Release identity | The installation stops if the loaded images and the bundle directory are from different releases. |
Behavior Changes
- Keycloak runs from a CertSecure image in production mode. After the upgrade is accepted, remove the previous Keycloak image, for example docker rmi quay.io/keycloak/keycloak:<OLD_TAG>.
- Earlier releases stored an internal Keycloak address in server.yaml, which prevents browser single sign-on. The installation corrects it and reports repointed IdServer server_url at https://<KEYCLOAK_HOSTNAME>/. This is expected.
- The optional MCP server is available. It is controlled by CERTSECURE_MCP_ENABLED, which is absent from earlier environment files and therefore off (see Enable the MCP Server in the Docker installation guide).
Recover a Lost Environment File
If the environment file of the current deployment is lost, do not run the installation of the new release: it would generate new secrets that the existing Keycloak and MongoDB do not recognize, and it stops. First look for the file in your backups, and check the previous docker/deploy/keycloak-credentials.txt, which contains the same generated values.
Important: If neither is available, contact Encryption Consulting support before you continue. Recovery requires the MongoDB password from the [Mongo] uri line of the previous docker/deploy/conf.ini, and resets the Keycloak service-account password.
Upgrade on a Windows Host
On a Windows host running Docker Desktop, the upgrade procedure is the same. Use PowerShell and the following equivalents.
Table 4: Windows Command Equivalents
| Linux | Windows (PowerShell) |
|---|---|
| OLD=/opt/certsecure/... | $OLD = 'C:\CertSecure\CertSecure-Docker-<CURRENT_VERSION>' |
| tar -xzf <BUNDLE>.tar.gz | tar -xzf <BUNDLE>.tar.gz |
| cp $OLD/docker/.env $NEW/docker/.env | Copy-Item $OLD\docker\.env $NEW\docker\.env |
| ./deploy-docker.sh | .\deploy-docker.ps1 |
| ./teardown-docker.sh | .\teardown-docker.ps1 |
| -v ~/certsecure-backup:/backup | -v C:/certsecure-backup:/backup |
| $(date +%F) | $(Get-Date -Format yyyy-MM-dd) |
| COMPOSE_PROFILES=mcp docker compose ... | $env:COMPOSE_PROFILES='mcp'; docker compose ... |
Troubleshoot the Upgrade
Table 5: Upgrade Troubleshooting
| Symptom | Cause | Resolution |
|---|---|---|
| The installation reports generating new secrets, or stops with a Keycloak secret mismatch. | .env was not copied from the current deployment. | Copy .env (see Upgrade, Step 2) and run the installation again. |
| The installation stops because the image and bundle are from different releases. | The script was run from the wrong bundle directory. | Run the script from the bundle directory of the release you want. |
| Realms added in the web UI are missing. | deploy/server.yaml was not copied. | Stop the containers, copy server.yaml from the previous bundle and run the installation again. |
| Browsers display a certificate warning again. | The certificate was stored inside the previous bundle and a new self-signed certificate was generated. | Copy certs-local from the previous bundle, or set the certificate paths in .env, and run the installation again. |
| Agent installer downloads return 404. | CERTSECURE_AGENTS_DIR points to a missing or empty directory. | Correct the path and run the installation again. |
| The installation stops with a MongoDB authentication message. | The current deployment is from a release without MongoDB authentication. | See Enable MongoDB Authentication on an Existing Database. |
| An upgrade that ran unattended now stops at a prompt. | The host is below the minimum specification. | Set CERTSECURE_ACK_UNDERSIZED=1 in .env. |
| A changed setting has no effect. | A generated file in docker/deploy/ was edited. | Make the change in .env and run the installation again. |