- Overview
- Reference Guide
- Setup & Architecture
- Release Notes
- Workflow
- API Reference
- Integration Guide
- Discovery Agent Setup Guide
Docker
Install CertSecure in Containers Under Docker Compose
CertSecure can be installed as a set of Docker containers on a single Linux or Windows host. When CertSecure is installed in containers, it runs as a Docker Compose stack of four containers, plus one optional container, connected by a private Docker network. A single nginx container is the only entry point, on one HTTPS port.
Table 1: CertSecure Containers
| Container | Image | Description |
|---|---|---|
| nginx | nginx:1.30 | Edge web server. Terminates TLS on port 443, serves the CertSecure web UI and reverse-proxies the API and Keycloak. |
| backend | certsecure-backend:3.4 | CertSecure application server: REST API, background refresh and scheduler. |
| mongo | mongo:8.0.21 | MongoDB database, the only data store. Runs with authentication enabled. |
| keycloak | certsecure-keycloak:3.4 | Identity provider (OIDC and single sign-on) with an embedded database. |
| mcp | certsecure-mcp:3.4 | Optional. Read-only MCP server for AI agents; also used by the in-product PKI Assistant. Not deployed unless enabled. |
All persistent data is kept in Docker named volumes. Containers can be stopped, recreated and upgraded without losing data.
Table 2: CertSecure Docker Volumes
| 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. |
CertSecure is delivered as a single release bundle, CertSecure-Docker-<VERSION>.tar.gz, that contains every container image, the web UI, the agent installers and the deployment scripts. Installing from the bundle requires no internet access, and the host requires no software other than Docker.
The installation consists of the following tasks:
- Confirm the host meets the requirements and install Docker (see Prerequisites for a Docker Installation).
- Transfer and verify the release bundle (see Prepare the Installation Files).
- Create the environment file (see Configure the Environment File).
- Run the installation (see Install).
- Verify the installation and complete the first sign-in (see Verify the Installation and Complete the First Sign-In).
Note: Commands in this section are shown for a Linux host. Where a Windows (PowerShell) command differs, both are given. Run all commands from the docker directory of the unpacked bundle unless a step says otherwise.
Prerequisites for a Docker Installation
Before you install CertSecure in containers, confirm that the host, network and certificate requirements in this section are met, and install Docker.
Host Requirements
The supported host specification is the same as for a CertSecure virtual machine installation.
Table 3: Host Requirements
| Resource | Minimum | Description |
|---|---|---|
| vCPU | 16 | Logical CPUs available to the host. |
| Memory | 32 GB | Total physical memory. |
| Disk | 300 GB | Provisioned size of the file system that holds Docker data (normally /var/lib/docker; on Windows, the system drive). |
| Free disk space | 10 GB | Free space on the same file system at installation time. This requirement cannot be overridden. |
| CPU architecture | x86_64 | The container images are built for linux/amd64. ARM hosts, such as AWS Graviton, are not supported. |
| CPU instruction set | AVX | Required by MongoDB. On a virtual machine, confirm the hypervisor exposes AVX to the guest. |
| Linux kernel | Below 6.19, or 7.0.14 and later | MongoDB 8 does not start on Linux kernels 6.19 through 7.0.13. |
The installation checks every requirement in Table 3 before it loads any image. If the host is below the vCPU, memory or disk minimum, the installation displays the shortfall and asks whether to continue; a deployment on such a host is suitable for test and evaluation only and is not a supported production configuration. If free disk space, CPU or kernel requirements are not met, the installation stops.
Important: MongoDB checks the kernel version when it starts, so a kernel update does not affect a running deployment until the next restart or reboot. If the host kernel is below 6.19, hold the kernel package (for example, add exclude=kernel* to /etc/dnf/dnf.conf, or run apt-mark hold on the kernel meta-package) until a 7.0.14 or later kernel is available.
Tip: To check for AVX on a Linux host, run grep -o avx /proc/cpuinfo | head -1. On a virtual machine, a missing AVX flag is usually caused by the hypervisor, for example a VMware EVC baseline that predates AVX, or a QEMU or Proxmox CPU type of kvm64 instead of host.
Supported Operating Systems
- Linux distributions supported by Docker Engine: Ubuntu, Debian, Red Hat Enterprise Linux, Rocky Linux, AlmaLinux, Fedora, SUSE Linux Enterprise Server and Amazon Linux.
- Windows 10, Windows 11 or Windows Server with Docker Desktop running in Linux containers mode.
Network and DNS Requirements
CertSecure uses three host names, all resolving to the IP address of the host. nginx routes requests by host name.
Table 4: Host Names
| Name | Description | Example |
|---|---|---|
| <UI_HOSTNAME> | Host name of the CertSecure web UI. | certsecure.example.com |
| <API_HOSTNAME> | Host name of the CertSecure API. Agents and connectors connect to this name. | api.example.com |
| <KEYCLOAK_HOSTNAME> | Host name of the Keycloak sign-in service. | kc.example.com |
- Create DNS records for all three host names. The three names must be different from each other.
- Allow inbound TCP port 443 (or the port set in CERTSECURE_HTTPS_PORT) from users, agents and connectors.
- Always connect by host name. A request to the IP address of the host reaches the web UI, not the API.
Certificate Requirements
nginx serves all three host names from one TLS certificate, so the certificate's Subject Alternative Name (SAN) extension must contain all three host names. The certificate and its private key must be PEM files. If you do not provide a certificate, the installation generates a self-signed certificate for testing.
Table 5: Certificate Options
| Option | Description | Use |
|---|---|---|
| Generated self-signed certificate | Leave the certificate settings at their defaults. The installation generates a certificate for the three host names, localhost and 127.0.0.1, valid for 825 days. | Testing and evaluation. Browsers display a warning. |
| Your certificate, stored outside the bundle | Store the PEM files in a directory such as /opt/certsecure/certs and set CERTSECURE_SSL_CERT and CERTSECURE_SSL_KEY to their absolute paths. | Recommended for production. Upgrades do not affect it. |
| Your certificate, stored inside the bundle | Store the PEM files in the bundle directory and set relative paths. | Supported, but the files must be copied again at every upgrade. |
License Requirements
Obtain a CertSecure license key from Encryption Consulting before you begin. The license is activated at the first sign-in (see Complete the First Sign-In).
Install Docker on a Host with Internet Access
CertSecure requires Docker Engine with the Docker Compose v2 plugin (the docker compose command). If docker compose version already returns a version, skip this section. The bundle includes an installer that installs Docker Engine and the Compose plugin only.
To install Docker on a host with internet access:
- Unpack the bundle and change to its docker directory (see Prepare the Installation Files).
-
Run the installer for the operating system.
-
On Linux, run the installer as root:
sudo ./install-prereqs.sh -
On Windows, run the installer from an elevated PowerShell session. Restart the host if the WSL2 setup requests it, then start Docker Desktop and confirm it is in Linux containers mode.
.\install-prereqs.ps1
-
-
On Linux, start a new login session so that your user's membership of the docker group takes effect. For example:
newgrp docker -
Confirm Docker is ready:
docker version docker compose version
Note: If docker info returns permission denied, the current session does not have the docker group membership yet. Log out and log in again.
Install Docker on an Offline Host
The CertSecure installation itself does not require internet access. Docker, however, is installed from operating system packages. On a host without internet access, either install Docker from an internal package repository mirror, or download the packages on a connected computer running the same operating system version and architecture and transfer them to the host. The procedures in this section use the second method.
Important: Download the packages on a computer with the same distribution, major version and architecture as the target host. Packages from a different version can fail to install or install with missing dependencies.
Red Hat Enterprise Linux, Rocky Linux, AlmaLinux and Fedora
To install Docker on an offline RHEL-family host:
-
On the connected computer, add the Docker repository and download the packages with their dependencies. For example:
sudo dnf -y install dnf-plugins-core sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo mkdir docker-rpms dnf download --resolve --alldeps --destdir docker-rpms \ docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-pluginNote: On Fedora, use https://download.docker.com/linux/fedora/docker-ce.repo.
- Copy the docker-rpms directory to the offline host.
-
On the offline host, install the packages from the local directory:
sudo dnf install --disablerepo='*' ./docker-rpms/*.rpm -
Start Docker, enable it at boot and add your user to the docker group:
sudo systemctl enable --now docker sudo usermod -aG docker $USER newgrp docker -
Confirm Docker is ready:
docker compose version
Ubuntu and Debian
To install Docker on an offline Ubuntu or Debian host:
- On the connected computer, browse to https://download.docker.com/linux/ubuntu/dists/ (or /linux/debian/dists/), open the directory for the target release code name (for example, noble for Ubuntu 24.04), then open pool/stable/amd64/.
-
Download the latest version of each of the following packages:
- containerd.io_<VERSION>_amd64.deb
- docker-ce_<VERSION>_amd64.deb
- docker-ce-cli_<VERSION>_amd64.deb
- docker-buildx-plugin_<VERSION>_amd64.deb
- docker-compose-plugin_<VERSION>_amd64.deb
- Copy the five .deb files to a directory on the offline host.
-
On the offline host, install the packages from that directory:
sudo dpkg -i ./*.debNote: If dpkg reports a missing dependency, download that package from the release's package archive on the connected computer, copy it across and run the command again.
-
Enable Docker and add your user to the docker group:
sudo systemctl enable --now docker sudo usermod -aG docker $USER newgrp docker -
Confirm Docker is ready:
docker compose version
Amazon Linux 2023
On Amazon Linux, Docker Engine is provided by the Amazon Linux repository and the Compose plugin is installed as a single file.
To install Docker on an offline Amazon Linux 2023 host:
-
On a connected Amazon Linux 2023 computer, download the Docker package with its dependencies and the Compose plugin:
mkdir docker-rpms dnf download --resolve --alldeps --destdir docker-rpms docker curl -fL -o docker-compose \ https://github.com/docker/compose/releases/download/v2.32.4/docker-compose-linux-x86_64 - Copy the docker-rpms directory and the docker-compose file to the offline host.
-
On the offline host, install Docker Engine and the Compose plugin:
sudo dnf install --disablerepo='*' ./docker-rpms/*.rpm sudo mkdir -p /usr/libexec/docker/cli-plugins sudo install -m 0755 docker-compose /usr/libexec/docker/cli-plugins/docker-compose -
Enable Docker and add your user to the docker group:
sudo systemctl enable --now docker sudo usermod -aG docker $USER newgrp docker -
Confirm Docker is ready:
docker compose version
Windows
To install Docker Desktop on an offline Windows host:
-
On a connected computer, download the following files:
- The Docker Desktop installer for Windows (AMD64), Docker Desktop Installer.exe, from https://docs.docker.com/desktop/.
- The Windows Subsystem for Linux package, wsl.<VERSION>.x64.msi, from https://github.com/microsoft/WSL/releases.
- Copy both files to the offline host.
-
In an elevated PowerShell session, enable the Windows features that WSL2 requires, then restart the host:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart Restart-Computer -
Install WSL, then install Docker Desktop:
msiexec /i wsl.<VERSION>.x64.msi /quiet Start-Process '.\Docker Desktop Installer.exe' -Wait -ArgumentList 'install','--quiet','--accept-license','--backend=wsl-2' - Start Docker Desktop, skip the sign-in, and confirm that it is in Linux containers mode.
-
Confirm Docker is ready:
docker compose version
Prepare the Installation Files
The release bundle is a single compressed archive. The following steps transfer the bundle to the host, confirm it was not damaged in transfer, and confirm it is the expected release.
To prepare the installation files:
-
On the computer where you downloaded the bundle, record its SHA-256 checksum. For example:
sha256sum CertSecure-Docker-<VERSION>.tar.gzNote: On Windows, use Get-FileHash CertSecure-Docker-<VERSION>.tar.gz -Algorithm SHA256.
- Copy the bundle to the host by any approved method, such as secure copy or removable media. For an offline host, use the transfer process your organization approves for the isolated network.
-
Create a directory from which you will run the installation, and copy the bundle into it. For example:
sudo mkdir -p /opt/certsecure sudo chown $USER: /opt/certsecure cp CertSecure-Docker-<VERSION>.tar.gz /opt/certsecure/ cd /opt/certsecure -
Calculate the checksum on the host and confirm that it matches the value recorded in step 1:
sha256sum CertSecure-Docker-<VERSION>.tar.gz -
Unpack the bundle and display its manifest:
tar -xzf CertSecure-Docker-<VERSION>.tar.gz cd CertSecure-Docker-<VERSION> cat BUNDLE-MANIFEST.txt -
Confirm that the manifest shows the expected product version and lists the container images. For example:
CertSecure Docker air-gap bundle product : 3.4 commit : <BUILD_COMMIT> archive : CertSecure-Docker-3.4.tar.gz agents : <COUNT> installer(s) in bin/Agents images : - certsecure-backend:3.4 - certsecure-keycloak:3.4 - certsecure-mcp:3.4 - mongo:8.0.21 - nginx:1.30 -
Change to the docker directory. All later commands run from this directory:
cd docker
Table 6: Bundle Contents
| Path | Description |
|---|---|
| docker/ | Compose file, installation scripts, configuration templates and images.tar.gz, which contains every container image. |
| UI/ | CertSecure web UI, served by nginx. |
| bin/Agents/ | Agent and connector installers offered for download in the web UI (approximately 520 MB). |
| conf/, install/ | Backend configuration and the Keycloak realm template used to generate the configuration. |
| BUNDLE-MANIFEST.txt | Release identification: product version, build commit, installer count and image list. |
Note: Keep the bundle directory for as long as this release is installed. The web UI and the agent installers are served from it, and it is used to roll back an upgrade.
Configure the Environment File
All deployment-specific settings for CertSecure are stored in one environment file, docker/.env. Every other configuration file is generated from this file each time the installation runs, including the backend configuration, the Keycloak realm, the nginx configuration and the web UI configuration.
Important: Do not edit the generated files in docker/deploy/. They are overwritten each time the installation runs. Make all changes in docker/.env.
To configure the environment file:
-
Create the environment file using one of the following methods:
-
Run the interactive configuration script. It prompts for each value, validates it and writes the file with permissions that allow only your user to read it.
./configure-env.sh # Linux .\configure-env.ps1 # Windows -
Copy the example file, restrict its permissions and edit it:
cp deploy/.env.example .env chmod 600 .env vi .env
-
-
Set the values in the file using the inputs in Table 7.
Note: When you enter a UI host name such as certsecure.acme.com, the configuration script proposes api.acme.com, kc.acme.com and the realm acme.com. Accept or change each value.
- Confirm that the three host names are different from each other and that your TLS certificate covers all three.
- Store a copy of the environment file securely. After the first installation it also contains generated secrets (see Install).
Important: Run the configuration script as your normal user, not with sudo. A root-owned environment file cannot be read by the installation script, which then reports that the Keycloak administrator password is missing.
Important: Choose the host names, realm name and client ID before the first installation. Keycloak imports the realm once, when it first starts. After that, the installation refuses to change the realm name, client ID or generated credentials, and changing them requires a new installation with empty data.
Table 7: CertSecure Docker Environment File Settings
| Name | Description | Example | Default |
|---|---|---|---|
| CERTSECURE_FRONTEND_HOST | Host name of the CertSecure web UI. | certsecure.acme.com | certsecure.local [required] |
| CERTSECURE_BACKEND_HOST | Host name of the CertSecure API. Agents and connectors connect to this name. | api.acme.com | api.certsecure.local [required] |
| CERTSECURE_KEYCLOAK_HOST | Host name of the Keycloak sign-in service. If blank, derived from the UI host name as kc.<base domain>. | kc.acme.com | keycloak.certsecure.local |
| CERTSECURE_KEYCLOAK_REALM | Keycloak realm name. Letters, digits, period, hyphen and underscore only. Must not contain the word default. | acme.com | example.com |
| CERTSECURE_KC_CLIENT_ID | Keycloak client ID used by CertSecure. | certsecure.acme.com | certsecure.<realm> |
| KC_BOOTSTRAP_ADMIN_USERNAME | User name for the Keycloak administration console. | kc-admin | admin-certsecure |
| KC_BOOTSTRAP_ADMIN_PASSWORD | Password for the Keycloak administration console. The containers do not start without it. | — | [blank, required] |
| CERTSECURE_SSL_CERT | Path on the host to the PEM TLS certificate. Absolute, or relative to the docker directory. The ~ character is not expanded. | /opt/certsecure/certs/cert.pem | ./certs-local/cert.pem (generated if absent) |
| CERTSECURE_SSL_KEY | Path on the host to the PEM private key for the certificate. | /opt/certsecure/certs/key.pem | ./certs-local/key.pem (generated if absent) |
| CERTSECURE_HTTPS_PORT | HTTPS port published on the host. A non-standard port is added to every generated URL. | 8443 | 443 |
| CERTSECURE_MCP_ENABLED | Set to 1 to deploy the optional MCP server (see Enable the MCP Server). | 1 | 0 |
| CERTSECURE_AGENTS_DIR | Directory on the host that holds the agent and connector installers. An absolute path outside the bundle is recommended. | /opt/certsecure/agents | ../bin/Agents |
| CERTSECURE_WORKERS | Number of application worker processes. | 8 | 4 |
| CERTSECURE_MONGO_USER | MongoDB user name. Set before the first installation only. | certsecure | certsecure |
| CERTSECURE_MONGO_URI | Connection string for an external MongoDB server, in the form mongodb://<USER>:<PASSWORD>@<HOST>:27017/?authSource=admin. When set, the bundled MongoDB container is not used. Percent-encode reserved characters in the password. | — | [blank] |
| CERTSECURE_IMAGE_TAG | Image tag to run. Used to pin a release or roll back. | 3.4 | latest |
| CERTSECURE_ACK_UNDERSIZED | Set to 1 to continue without prompting on a host below the minimum specification. Required for unattended installation on such a host. Does not override the free disk space check. | 1 | [blank] |
Install
The installation script loads the container images from the bundle, generates the configuration from the environment file, starts the containers and waits until they are healthy. It does not require internet access, and it can be run again at any time without affecting existing data.
To install CertSecure in containers under Docker Compose:
- Confirm that you are in the docker directory of the unpacked bundle and that .env exists.
-
Run the installation script:
./deploy-docker.sh # Linux .\deploy-docker.ps1 # WindowsImportant: Do not use the --build (Linux) or -Build (Windows) option. It builds the images from source, requires internet access and is not needed when installing from a release bundle.
- If the host is below the minimum specification, review the shortfall displayed and enter y to continue, or n to stop.
-
Wait for the script to report that the stack is up. On the first installation this takes several minutes while Keycloak imports the realm. The script displays each check as it runs; any [ fail ] line stops the script and describes what to correct.
The script ends by displaying the access URLs. For example:
[ ok ] CertSecure stack is up. Access (via the nginx edge on :443): UI https://certsecure.acme.com API https://api.acme.com Keycloak https://kc.acme.com -
Back up the environment file and the credentials file to a secure location. For example:
cp .env deploy/keycloak-credentials.txt <SECURE_BACKUP_LOCATION>/Important: On the first installation, the script generates a Keycloak client secret, a Keycloak service-account password, an application secret key and a MongoDB password, and appends them to .env. They are reused by every later installation and upgrade and cannot be recovered from the database. Do not edit or remove the generated block in .env.
Table 8: Installation Checks
| Check | Description |
|---|---|
| Docker and kernel | Confirms Docker and the Compose plugin are available and that the kernel is compatible with MongoDB. |
| Environment file | Confirms .env exists and contains a Keycloak administrator password. |
| Agent installers | Displays the number of agent installers found. A count of zero means downloads will fail. |
| Host specification | Compares vCPU, memory and disk with the minimum specification, and checks free disk space. |
| Image load | Loads all container images from images.tar.gz. |
| Release identity | Confirms that the loaded images and the bundle directory belong to the same release. |
| CPU | Confirms that the CPU supports AVX. |
| Configuration | Generates the configuration files from .env, and the secrets on the first installation. |
| Health | Starts the containers and waits until MongoDB, Keycloak and the backend report healthy. |
The following files contain secrets. Restrict access to them and include them in your backups.
Table 9: Files Containing Secrets
| File | Contents |
|---|---|
| docker/.env | Deployment settings plus the generated Keycloak client secret, Keycloak service-account password, application secret key and MongoDB password. |
| docker/deploy/keycloak-credentials.txt | Keycloak admin console URL, realm details and the generated credentials. |
| docker/deploy/conf.ini | Generated backend configuration, including the MongoDB connection string and its password. |
| docker/deploy/server.yaml | Generated Keycloak realm configuration. Also updated by the Manage Realms page. |
Tip: To review the logs of a container, use docker compose logs. For example, to follow the application log, run docker compose logs -f backend. To show the last lines only, run docker compose logs --tail 200 backend.
Verify the Installation
To verify the installation:
-
Display the container status and confirm that mongo, keycloak and backend are healthy and nginx is running:
docker compose ps -
Confirm that the API responds with the product 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_windowsNote: A 404 status means the agent installer directory is missing or empty (see Configure Agents and Connectors).
-
Confirm that Keycloak imported the realm:
docker compose logs keycloak | grep -i import
Note: The -k option allows curl to accept a self-signed certificate. Omit it when a trusted certificate is installed.
Complete the First Sign-In
After installation, create the first CertSecure administrator and activate the license.
To complete the first sign-in:
- In a browser, go to https://<UI_HOSTNAME>. If the installation uses the generated self-signed certificate, accept the browser warning.
-
If the installation uses the generated self-signed certificate, also go to https://<API_HOSTNAME> and https://<KEYCLOAK_HOSTNAME> and accept the browser warning for each.
Important: A self-signed certificate must be accepted separately for each host name. The web UI calls the API in the background, and the browser blocks that call without displaying a warning if the API certificate has not been accepted. The web UI then displays a general error during onboarding.
- Complete the CertSecure administrator onboarding. This creates the first administrator account.
- Activate the CertSecure license key.
- Confirm that the dashboard is displayed.
To manage Keycloak, go to https://<KEYCLOAK_HOSTNAME> and sign in with the values of KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD from .env.
Enable the MCP Server
The CertSecure MCP server provides AI agents, such as Claude Desktop, Claude Code or your own agent, with read-only access to certificate data. The in-product PKI Assistant also uses it. The MCP server is optional and is not deployed by default. Its container image is included in the bundle, so it can be enabled at any time without internet access.
- The MCP server is reachable only through nginx, at https://<API_HOSTNAME>/mcp. No additional port is opened on the host.
- Every request must include a valid CertSecure session or an API token created in the web UI.
- Each user sees only the certificate authorities that their role and department allow.
- Model provider API keys (Anthropic, OpenAI) are not stored in any deployment file. They are stored encrypted in the database and managed on the PKI Assistant administration page.
- Use of the PKI Assistant requires the Use AI Assistant permission. By default, only administrators hold it.
To enable the MCP server:
-
In .env, set the following value:
CERTSECURE_MCP_ENABLED=1 -
Run the installation script again:
./deploy-docker.sh -
Confirm that the MCP container is healthy:
COMPOSE_PROFILES=mcp docker compose ps mcp -
Confirm that the MCP server enforces authentication. The command must return 401:
curl -k -s -o /dev/null -w '%{http_code}\n' https://<API_HOSTNAME>/mcp
Table 10: MCP Server Responses
| Response | Meaning |
|---|---|
| 401 | The MCP server is running and enforcing authentication. This is the expected response. |
| 502 | The MCP container is not running, or CERTSECURE_MCP_ENABLED is 0. |
| 421 | The request used a host name other than CERTSECURE_BACKEND_HOST. Correct the setting and run the installation again. |
To connect an AI client to the MCP server:
- In the CertSecure web UI, create an API token.
-
Register the MCP server with the client using the token. For example, for Claude Code:
claude mcp add --transport http certsecure \ https://<API_HOSTNAME>/mcp \ --header "Authorization: Bearer <API_TOKEN>"
Note: Use the path /mcp exactly, without a trailing slash. docker compose commands that should include the MCP container require COMPOSE_PROFILES=mcp. To remove the MCP server, set CERTSECURE_MCP_ENABLED=0 and run the installation script again.
Configure Agents and Connectors
CertSecure agents and connectors are downloaded from the web UI. The installers are served from the bin/Agents directory of the bundle, or from the directory set in CERTSECURE_AGENTS_DIR.
- Configure each agent with the API host name, for example api.acme.com, not the IP address of the host.
- Confirm that the agent host can resolve the API host name and reach TCP port 443, or the port set in CERTSECURE_HTTPS_PORT.
- Signed installer builds placed in a Signed subdirectory are used in preference to unsigned builds and can be added without running the installation again.
To store the agent installers outside the bundle:
-
Create a directory and copy the installers into it. For example:
sudo mkdir -p /opt/certsecure/agents sudo cp -r ../bin/Agents/. /opt/certsecure/agents/ -
In .env, set the directory as an absolute path:
CERTSECURE_AGENTS_DIR=/opt/certsecure/agents - Run ./deploy-docker.sh and confirm that the installer count it displays is not zero.
Important: If the directory does not exist, Docker creates it empty. The installation then succeeds, but every installer download returns 404.
Operate the Deployment
Common Commands
Run the following commands from the docker directory.
Table 11: Common Commands
| Task | Command |
|---|---|
| Display status | docker compose ps |
| Follow a container log | docker compose logs -f backend |
| Restart the application | docker compose restart backend |
| Apply a replaced TLS certificate | docker compose restart nginx backend |
| Apply a change to .env | ./deploy-docker.sh |
| Stop the deployment (data is kept) | docker compose down |
| Start the deployment | ./deploy-docker.sh |
Important: Do not add the -v option to docker compose down. docker compose down -v permanently deletes the MongoDB and Keycloak volumes and all CertSecure data.
Back Up and Restore
Back up the MongoDB and Keycloak volumes on a regular schedule, together with the files in Table 9. The following procedure creates a consistent file-level backup while the containers are stopped. It uses the MongoDB image already on the host, so it does not require internet access.
To back up the deployment:
-
Stop the containers:
docker compose down -
Archive the MongoDB and Keycloak volumes:
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 . -
Copy the configuration files:
cp .env deploy/server.yaml deploy/keycloak-credentials.txt ~/certsecure-backup/ -
Start the containers:
./deploy-docker.sh
To restore the deployment from a backup:
-
Stop the containers:
docker compose down -
Restore each volume from its archive. For example:
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' -
Start the containers:
./deploy-docker.sh
Note: On Windows, replace ~/certsecure-backup with a full path such as C:/certsecure-backup, and $(date +%F) with $(Get-Date -Format yyyy-MM-dd). On Linux, the archives are owned by root; use sudo chown to change their owner.
Remove the Deployment
Table 12: Removal Commands
| Command | Description |
|---|---|
| ./teardown-docker.sh | Removes the containers and the network. All data is kept. |
| ./teardown-docker.sh --volumes | Also deletes all volumes and all CertSecure data. Prompts for confirmation. |
| ./teardown-docker.sh --images | Also removes the CertSecure container images. |
| ./teardown-docker.sh --all --yes | Removes containers, network, volumes and images without prompting. |
On Windows, use .\teardown-docker.ps1 with the -Volumes, -Images, -All and -Yes options.
Troubleshoot the Installation
Table 13: Installation Troubleshooting
| Symptom | Cause | Resolution |
|---|---|---|
| The installation stops with a kernel compatibility message. | The kernel is 6.19 through 7.0.13. | Install a kernel below 6.19, or 7.0.14 or later, and run the installation again. |
| The installation stops with an AVX message. | The CPU, or the hypervisor configuration, does not expose AVX. | Enable AVX for the virtual machine, then run the installation again. |
| The installation stops with a disk space message. | Less than 10 GB is free on the Docker data file system. | Free disk space and run the installation again. |
| The installation reports that the administrator password is empty. | .env was created with sudo and cannot be read. | Run sudo chown $USER .env and run the installation again. |
| The installation stops because the image and bundle are from different releases. | The script was run from a different bundle directory than the loaded images. | Run the script from the bundle directory of the release you are installing. |
| The web UI displays an error during onboarding. | The self-signed certificate was not accepted for the API and Keycloak host names. | Accept the certificate for each host name (see Complete the First Sign-In). |
| Agent installer downloads return 404. | The agent installer directory is missing or empty. | Correct CERTSECURE_AGENTS_DIR (see Configure Agents and Connectors). |
| Sign-in is refused and the realm is reported as not initialized. | The realm name contains default, or the Keycloak host name does not resolve. | Correct the realm name or DNS before the first installation. |
| The mongo container is unhealthy. | Usually the kernel or AVX requirement. | Review docker compose logs mongo. |
| The browser still reports Not secure after a trusted certificate is installed. | The browser kept the earlier exception for the self-signed certificate. | Open the site in a private window to confirm, then clear the site settings. |
| The installation tries to download images. | images.tar.gz is missing from the docker directory, or --build was used. | Unpack the complete bundle again and run the script without --build. |
When you contact Encryption Consulting support, provide the output of the installation script, docker compose ps and docker compose logs --tail 300 backend.
Important: Do not send .env, deploy/conf.ini or deploy/keycloak-credentials.txt to support. They contain secrets.