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. With latest, 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 history records 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/health

The 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.

  1. In docker-compose.yml, set the image tag to the target version:

    services:
      socket-firewall:
        image: socketdev/socket-registry-firewall:NEW_VERSION
  2. Pull the new image:

    docker compose pull socket-firewall
  3. Recreate the container on the new image:

    docker compose up -d socket-firewall
  4. Check the result with the steps in Verify the upgrade.

Replace the following:

  • NEW_VERSION: the firewall version you're moving to, such as 2.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.

  1. Pull the new image:

    docker pull socketdev/socket-registry-firewall:NEW_VERSION
  2. Stop and remove the old container:

    docker stop socket-firewall
    docker rm socket-firewall
  3. 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
  4. Check the result with the steps in Verify the upgrade.

Replace the following:

  • NEW_VERSION: the firewall version you're moving to, such as 2.21.1.

Upgrade a tarball build

These steps apply to images you build from the firewall tarball, as described in the Installation Guide.

  1. Download the new tarball for your architecture from the release notes page. Download entrypoint.sh from the same repository again, because it can change between releases.

  2. In your Dockerfile, change the tarball filename in the COPY line to the new file.

  3. 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
  4. Recreate the container on the new image:

    docker compose up -d socket-firewall
  5. Check the result with the steps in Verify the upgrade.

Replace the following:

  • NEW_VERSION: the firewall version in the tarball filename, such as 2.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 stays Pending and 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.pem
tls:
  generateSelfSigned: false
  existingSecret: socket-firewall-tls
  1. Refresh the chart repository and list the available versions:

    helm repo update
    helm search repo socket-firewall --versions

    The 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       ...
  2. Save the values your release uses today:

    helm get values RELEASE -n NAMESPACE -o yaml > firewall-values.yaml

    The 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.

  3. In firewall-values.yaml, set image.tag to 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 set image.tag.

  4. Upgrade the release:

    helm upgrade RELEASE REPO_NAME/socket-firewall -n NAMESPACE \
      --version CHART_VERSION -f firewall-values.yaml

    Pass your values with -f instead 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: deployed as soon as Kubernetes accepts the change, before any new pod is ready. Step 5 confirms the pods.

  5. 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 NAMESPACE

    The rollout is complete when the output reads deployment "DEPLOYMENT" successfully rolled out. If it keeps printing old replicas are pending termination, see New pods stay Pending or never become ready.

  6. Check the result with the steps in Verify the upgrade.

Replace the following:

  • RELEASE: your Helm release name. List releases with helm list -A.
  • NAMESPACE: the namespace the firewall runs in.
  • REPO_NAME: the name you gave the Socket chart repository. List repositories with helm repo list.
  • CHART_VERSION: the chart version from step 1, such as 0.11.26.
  • NEW_VERSION: the firewall version you're moving to, such as 2.21.1.
  • DEPLOYMENT: the Deployment name from step 5. It's the release name, or RELEASE-socket-firewall when the release name doesn't contain socket-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/health

The 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.yml and run docker 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 run helm 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_VERSION

If 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 memory or Insufficient cpu, the cluster has no room for the extra pod. Add node capacity, or lower resources.requests in 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.


Did this page help you?