Patch Application

This page provides a step-by-step walkthrough for applying a client-specific patch (delivered as a .zip file) to a running SigningHub Docker-based deployment. This mode is designed to update existing SigningHub services in-place while preserving the current configuration and container state.

The wizard-style approach is not used in this process; instead, patching is performed manually through controlled container operations, ensuring minimal disruption to running services.

---

Overview

A patch ZIP file mirrors the internal directory structure of the SigningHub application (/app inside the container). Applying the patch means extracting it directly into /app, which automatically overwrites only the files included in the patch.

No manual file mapping is required.

Important: Do not recreate or redeploy containers while applying a patch. Recreating containers (e.g., docker compose up --force-recreate) removes the writable container layer and results in loss of applied patch changes. The correct approach is to copy and extract the patch into a running container and then restart it using docker restart, which preserves the installation state.

---

Prerequisites

Requirement	Details
Server access	SSH access to the host running the SigningHub Docker deployment
Docker	Installed and running (docker --version)
Docker Compose	Installed (docker compose version)
Patch ZIP file	Copied to the host server before starting
Permissions	User must have Docker execution rights (root or docker group access)

---

Container Reference

Container Name	Service	App Directory	Port
signinghub-admin-api	Admin API	/app/admin-api/	8084
signinghub-api	Web API	/app/api/	8082
signinghub-web	Web Frontend	/app/web/	8080
signinghub-admin	Admin Frontend	/app/admin/	8081
signinghub-core	Core Service	/app/core/	8086

All SigningHub service containers share the same application root: /app.

Infrastructure services (such as database, cache, and mail services) are not part of patch deployment.

---

Patch Application Flow

This section outlines the steps to apply a patch to a running SigningHub Docker container. The patch is applied directly into the existing container without recreating it, ensuring that the current configuration and data remain intact.

Follow the steps to safely copy, apply, and activate the patch on the target service.

---

Step 1: Identify Running Containers

Verify that SigningHub services are running before applying the patch:

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

Confirm that required services are in an Up (healthy) state.

---

Step 2: Identify Target Container

The patch may be service-specific or apply to multiple services.

Use the Container Reference table to identify the correct container.

Recommended execution order (if multiple services are affected):

signinghub-admin-api → signinghub-api → signinghub-core → signinghub-web → signinghub-admin

---

Step 3: Copy Patch to Container

Copy the patch ZIP file into the container:

docker cp /path/to/patch.zip <container>:/tmp/patch.zip

Example:

docker cp /opt/patches/admin-api-patch.zip signinghub-admin-api:/tmp/patch.zip

Verify file transfer:

docker exec <container> ls -lh /tmp/patch.zip

---

Step 4: Extract Patch

Extract the patch into the application directory inside the container:

docker exec <container> unzip -o /tmp/patch.zip -d /app

This will overwrite only the files included in the patch package.

---

Step 5: Apply Patch

Ensure correct permissions are applied after extraction:

docker exec <container> chmod -R 0777 /app

---

Step 6: Remove Patch File

Clean up the temporary file:

docker exec <container> rm -f /tmp/patch.zip

---

Step 7: Restart Container

Restart the container to apply the changes:

docker restart <container>

Example:

docker restart signinghub-admin-api

The container will restart using the existing installation state and will not trigger reinstallation.

---

1. If the patch applies to multiple services, repeat steps 3 to 7 for each container.

---

Validation

1. Check Container Status

docker ps --filter "name=<container>"

Ensure the container status is Up.

---

2. Check Logs

docker logs -f <container> --tail 100

Look for successful startup messages.

---

3. Verify Service Response

curl -k -fsS https://localhost:<port>/ -o /dev/null -w "%{http_code}\n"

A valid HTTP response confirms the service is running.

---

4. Confirm Patch Applied

Verify a known patched file exists:

docker exec <container> ls -lh /app/<patched-file-path>

---

1. After applying the patch, the DB scripts provided in the patch zip file need to be manually executed.

2. The patch ZIP structure must match the internal /app directory structure.

3. Containers must not be recreated during patching.

4. Only docker restart should be used after applying a patch.

5. Patch operations are in-place and do not modify the database configuration or data.

6. If multiple services are patched, always follow dependency order to avoid service disruption.

7. Ensure backups are taken before applying patches in production environments.

8. If a container fails after a restart, review the logs using docker logs.