homelab-blueprint/docker-compose-files/socket-proxy

Beszel Socket Proxy

Restricted Docker socket proxy for the Beszel agent. Run all commands from the repository root.

Appdata Location

This stack does not use appdata/. It mounts the host Docker socket read-only.

Installation

1. Create .env if it does not exist:

   cp -n .env.sample .env
   

2. Review the proxy values in .env:

   BESZEL_SOCKET_PROXY_BIND_IP=127.0.0.1
   BESZEL_SOCKET_PROXY_PORT=2375
   BESZEL_SOCKET_PROXY_LOG_LEVEL=info
   BESZEL_SOCKET_PROXY_MEM_LIMIT=64m
   DOCKERLOGGING_MAXFILE=3
   DOCKERLOGGING_MAXSIZE=10m
   

3. Render the template:

   ./substitute_env.sh docker-compose-files/socket-proxy/template.yaml docker-compose.beszel-proxy.yml .env
   

4. Validate and start the proxy:

   docker compose -f docker-compose.beszel-proxy.yml config --quiet
   docker compose -f docker-compose.beszel-proxy.yml up -d
   

5. Verify the container:

   docker compose -f docker-compose.beszel-proxy.yml ps
   docker compose -f docker-compose.beszel-proxy.yml logs --tail=100 beszel-proxy
   

Apply Configuration Changes

./substitute_env.sh docker-compose-files/socket-proxy/template.yaml docker-compose.beszel-proxy.yml .env
docker compose -f docker-compose.beszel-proxy.yml up -d

Initial Setup

Start this stack before the Beszel agent.

Network Requirements

Keep BESZEL_SOCKET_PROXY_BIND_IP=127.0.0.1 so the Docker API is not exposed on the LAN.

Troubleshooting

Confirm Docker can read /var/run/docker.sock and that port 2375 is not already in use.

Useful Commands

curl http://127.0.0.1:2375/_ping

Backup

No persistent stack data requires backup.