Upgrade the Firewall
Move a self-hosted Socket Registry Firewall to a new version with Docker Compose, docker run, a tarball build, or Helm on Kubernetes.
Upgrade the Firewall
To upgrade Socket Registry Firewall, point your deployment at a new image tag and restart it. Your socket.yml, API token, and TLS certificate carry over as long as you keep the same mounts, secrets, and values. This page covers Docker Compose, docker run, tarball builds, and Helm on Kubernetes.
Prepare for the upgrade
Complete these checks before you change anything:
- Pick the target version from the Socket Firewall release notes, and read the notes for every version between yours and the target.
- Pin an exact tag, such as
2.21.1. Withlatest, any restart can change your version, and you have no known tag to roll back to. - Record the version you run now. The health endpoint returns it, and on Helm
helm historyrecords each revision. - Confirm your TLS certificate lives outside the container. The firewall generates a self-signed certificate only when none exists, so a container or pod that starts without the old certificate creates a new one. Clients that trusted the old certificate then fail TLS checks.
This command prints the running version from the health endpoint:
curl -fk https://localhost:8443/healthThe response starts with SocketFirewall/ followed by the version, for example SocketFirewall/2.20.1 - Health OK.
Upgrade with Docker Compose
These steps apply to the pre-built image deployed with the Installation Guide. Keep the ./ssl:/etc/nginx/ssl volume in place so the new container reuses your certificate.
-
In
docker-compose.yml, set the image tag to the target version:services: socket-firewall: image: socketdev/socket-registry-firewall:NEW_VERSION -
Pull the new image:
docker compose pull socket-firewall -
Recreate the container on the new image:
docker compose up -d socket-firewall -
Check the result with the steps in Verify the upgrade.
Replace the following:
NEW_VERSION: the firewall version you're moving to, such as2.21.1.
Compose replaces the container in place. The old container keeps serving until it stops, which can take up to 10 seconds, and the firewall is unavailable for a few seconds while the new container starts. To avoid the gap, run two or more instances behind a load balancer and upgrade them one at a time.
Upgrade with docker run
These steps replace a container started with docker run. If you don't have the original command, this prints the old container's port bindings and volumes before you remove it:
docker inspect socket-firewall \
--format '{{json .HostConfig.PortBindings}} {{range .Mounts}}{{.Source}}:{{.Destination}} {{end}}'The firewall is unavailable from the moment the old container stops until the new one starts, usually a few seconds.
-
Pull the new image:
docker pull socketdev/socket-registry-firewall:NEW_VERSION -
Stop and remove the old container:
docker stop socket-firewall docker rm socket-firewall -
Start a new container with the same ports, volumes, and environment variables, using the new tag:
docker run -d --name socket-firewall \ -p 8080:8080 -p 8443:8443 \ -e SOCKET_SECURITY_API_TOKEN \ -v "$(pwd)/socket.yml:/app/socket.yml:ro" \ -v "$(pwd)/ssl:/etc/nginx/ssl" \ --restart unless-stopped \ socketdev/socket-registry-firewall:NEW_VERSION -
Check the result with the steps in Verify the upgrade.
Replace the following:
NEW_VERSION: the firewall version you're moving to, such as2.21.1.
Upgrade a tarball build
These steps apply to images you build from the firewall tarball, as described in the Installation Guide.
-
Download the new tarball for your architecture from the release notes page. Download
entrypoint.shfrom the same repository again, because it can change between releases. -
In your
Dockerfile, change the tarball filename in theCOPYline to the new file. -
Rebuild the image and tag it with the new version:
docker compose build docker tag my-registry.company.com/socket-firewall:latest \ my-registry.company.com/socket-firewall:NEW_VERSION -
Recreate the container on the new image:
docker compose up -d socket-firewall -
Check the result with the steps in Verify the upgrade.
Replace the following:
NEW_VERSION: the firewall version in the tarball filename, such as2.21.1.
Upgrade with Helm on Kubernetes
These steps upgrade a release installed from the Socket Firewall Helm chart (socket-firewall). Each chart version ships a default firewall version, shown as its app version.
Before you start, confirm these prerequisites:
- The cluster has room for one extra firewall pod. The rolling update starts a new pod before it stops an old one, and each pod requests 2 CPU and 8 GiB of memory by default (
resources.requests). Without that room, the new pod staysPendingand the upgrade stalls. - The pods load their TLS certificate from a Secret. With
tls.generateSelfSigned: true, every new pod generates a new CA, so clients that trust the old CA fail TLS checks after the upgrade. Clients behind an Ingress or load balancer that terminates TLS are unaffected.
To serve your own certificate, create a Secret with the keys fullchain.pem and privkey.pem and reference it in your values. If cert-manager issues the certificate, also set tls.certManager: true, and the chart reads the tls.crt and tls.key keys instead.
kubectl create secret generic socket-firewall-tls -n NAMESPACE \
--from-file=fullchain.pem=fullchain.pem --from-file=privkey.pem=privkey.pemtls:
generateSelfSigned: false
existingSecret: socket-firewall-tls-
Refresh the chart repository and list the available versions:
helm repo update helm search repo socket-firewall --versionsThe output lists each chart version with the firewall version it ships:
NAME CHART VERSION APP VERSION DESCRIPTION REPO_NAME/socket-firewall 0.11.26 2.21.1 ... -
Save the values your release uses today:
helm get values RELEASE -n NAMESPACE -o yaml > firewall-values.yamlThe file includes every value you passed at install, including secrets such as
socket.apiToken. Keep it out of version control, and delete it after the upgrade. -
In
firewall-values.yaml, setimage.tagto the target version:image: tag: "NEW_VERSION"We recommend the newest chart version whose app version matches
NEW_VERSION. If the firewall version you need is newer than every chart's app version, use the newest chart and setimage.tag. -
Upgrade the release:
helm upgrade RELEASE REPO_NAME/socket-firewall -n NAMESPACE \ --version CHART_VERSION -f firewall-values.yamlPass your values with
-finstead of--reuse-values. With--reuse-values, Helm keeps the old chart's computed values and skips defaults that newer chart versions add.Helm prints
STATUS: deployedas soon as Kubernetes accepts the change, before any new pod is ready. Step 5 confirms the pods. -
Find the Deployment and wait for the rollout to finish:
kubectl get deployments -n NAMESPACE -l app.kubernetes.io/instance=RELEASE kubectl rollout status deployment/DEPLOYMENT -n NAMESPACEThe rollout is complete when the output reads
deployment "DEPLOYMENT" successfully rolled out. If it keeps printingold replicas are pending termination, see New pods stay Pending or never become ready. -
Check the result with the steps in Verify the upgrade.
Replace the following:
RELEASE: your Helm release name. List releases withhelm list -A.NAMESPACE: the namespace the firewall runs in.REPO_NAME: the name you gave the Socket chart repository. List repositories withhelm repo list.CHART_VERSION: the chart version from step 1, such as0.11.26.NEW_VERSION: the firewall version you're moving to, such as2.21.1.DEPLOYMENT: the Deployment name from step 5. It's the release name, orRELEASE-socket-firewallwhen the release name doesn't containsocket-firewall.
The chart uses the Kubernetes default rolling update and a readiness probe on /health, so new pods take traffic only after they pass the health check. With one replica (the chart default), Kubernetes starts the new pod before it stops the old one, and the firewall keeps serving throughout the upgrade.
Verify the upgrade
Confirm the new version is running and that installs still work.
For Docker Compose, docker run, and tarball builds, check the health endpoint:
curl -fk https://localhost:8443/healthThe response starts with SocketFirewall/NEW_VERSION - Health OK.
For Helm, list the image on each pod:
kubectl get pods -n NAMESPACE -l app.kubernetes.io/instance=RELEASE \
-o 'custom-columns=NAME:.metadata.name,READY:.status.containerStatuses[0].ready,IMAGE:.spec.containers[0].image'Every pod shows true under READY and socketdev/socket-registry-firewall:NEW_VERSION under IMAGE. An old pod can stay in the list for up to 30 seconds while it shuts down.
Then install a package through the firewall from a client already configured to use it. For example, with npm path routing:
npm install lodash --registry FIREWALL_URL/npm/Replace FIREWALL_URL with the address your clients use for the firewall, such as https://sfw.company.com:8443. The install succeeds.
Roll back an upgrade
If the new version misbehaves, return to the version you recorded before the upgrade. Rolling back changes only the image; your configuration and certificates stay as they are.
- Docker Compose: set the old tag in
docker-compose.ymland rundocker compose up -d socket-firewall. - docker run: repeat the docker run steps with the old tag.
- Tarball build: recreate the container from the image tag you built for the old version.
- Helm: find the previous revision with
helm history RELEASE -n NAMESPACE, then runhelm rollback RELEASE REVISION -n NAMESPACE.
Related topics
Troubleshooting
Clients fail TLS checks after the upgrade
The new container or pod generated a new self-signed certificate because it couldn't find the old one. Its startup logs show SSL certificates not found, generating self-signed certificates. For Docker, restore your certificate files to the ssl directory mounted at /etc/nginx/ssl and recreate the container. For Helm, move the certificate into a Secret referenced by tls.existingSecret and upgrade again, or distribute the new CA to your clients.
The new image fails to pull
The tag doesn't exist on Docker Hub. A GitHub release can appear before its image is published. This command checks whether a tag exists:
docker manifest inspect socketdev/socket-registry-firewall:NEW_VERSIONIf the tag is missing, wait for the image or pick another version, and keep running the current one.
New pods stay Pending or never become ready
The rollout stalls, and the old pods keep serving traffic. Find the cause with kubectl describe pod -n NAMESPACE POD, where POD is the new pod's name from kubectl get pods:
- If the events show
Insufficient memoryorInsufficient cpu, the cluster has no room for the extra pod. Add node capacity, or lowerresources.requestsin your values if your workload allows it, and upgrade again. - If the pod starts but fails its readiness check, read its logs with
kubectl logs -n NAMESPACE POD.
To return to the previous version, run helm rollback as described in Roll back an upgrade. Rolling back removes the stalled pod.
Updated about 2 hours ago