Prerequisites

Everything on this page is needed before Block installs with Firewall. Plan on about 15 minutes for a fresh Linux VM.

Checklist

📘

Sizing

Socket doesn't publish minimum sizing. These pages were tested on a 4 vCPU / 6 GB Ubuntu 24.04 VM. Start there for a POC and watch CPU and memory under your real install load.

1. Install Docker and the tools

Ubuntu 22.04 / 24.04 or Debian 12 (least work, using the distribution's packages):

sudo apt update
sudo apt install -y docker.io docker-compose-v2 openssl curl jq
sudo usermod -aG docker "$USER"
newgrp docker      # or log out and back in

Other Linux distributions: follow Install Docker Engine for your distribution, which includes the Compose plugin, then install openssl, curl, and jq with your package manager.

macOS or Windows (local testing only): Docker Desktop includes Compose. Use a Linux host for anything other people will depend on.

Check the versions:

docker --version             # 20.10 or later
docker compose version       # v2.0 or later

🚧

Use docker compose, not docker-compose

The pages use the Compose v2 plugin (docker compose, with a space). The old standalone docker-compose (v1) is not supported.

2. Pull the firewall image

The image is published on Docker Hub as socketdev/socket-registry-firewall. It is public, so no Docker Hub login is needed.

docker pull socketdev/socket-registry-firewall:latest

latest is fine for a POC. For anything longer-lived, pin a version tag from the Docker Hub page (for example :2.16.0) and use the same tag in docker-compose.yml, so a restart never pulls an unexpected upgrade.

📘

Docker Hub rate limits

Anonymous pulls are rate-limited per IP address. If many machines share one outbound IP and pulls fail with toomanyrequests, run docker login with any Docker Hub account first.

No internet access on the firewall host?

Pull on a machine that has access, then move the image:

# On the connected machine. Match the target's architecture: linux/amd64 or linux/arm64
docker pull --platform linux/amd64 socketdev/socket-registry-firewall:2.16.0
docker save socketdev/socket-registry-firewall:2.16.0 -o socket-registry-firewall-2.16.0.tar

# Copy the .tar to the firewall host, then:
docker load -i socket-registry-firewall-2.16.0.tar

Or push it to your internal container registry and pull from there. The firewall still needs outbound HTTPS to api.socket.dev and the upstream registries at runtime. If your policy requires building images yourself, see the tarball method in the Installation Guide.

3. Create the API key

Dashboard → Settings → API Tokens → create a key with these scopes:

• packages:list
• entitlements:list

This key goes in the firewall's .env in the next page. It doesn't need policy or admin scopes. The Policy config automation examples use a separate admin key.

4. Open the network paths

If outbound traffic must go through a corporate proxy, see the outbound proxy settings in the Configuration Reference.

Verify

docker run --rm hello-world | grep -i "hello from docker"
docker compose version
docker image inspect socketdev/socket-registry-firewall:latest --format '{{.Architecture}}'
curl -sI https://api.socket.dev | head -1
curl -sI https://registry.npmjs.org | head -1

• Docker runs a container without sudo
• docker compose version shows v2 or later
• The image is present, and its architecture matches the host (uname -m: x86_64 means amd64, aarch64 means arm64)
• api.socket.dev and the registries answer from the firewall host
• You have the API key and a hostname for the firewall

Troubleshooting

Next

Block installs with Firewall.