Tiny single-binary load balancer and reverse proxy, Traefik-style rules. FROM scratch, ~9 MB.
63
A tiny, single-binary load balancer and reverse proxy with Traefik-style routing rules, written in Go.
The image is built FROM scratch: about 9 MB, with only the static picolb binary, the CA certificate
bundle and a starter config. No shell, no libc, no package manager. Available for linux/amd64 and linux/arm64.
Host(...), PathPrefix(...), and more), with prioritiesIt is not all of Traefik. Check the "What is not implemented" list in the project README before relying on it.
Try it with the starter config (plain HTTP on port 80, no routes yet). Every request gets a styled 404 page, which shows it runs:
docker run -d --name picolb -p 80:80 garfieldwtf/picolb
curl -i localhost/
Put your picolb.json in a folder, and keep a volume for certificates:
mkdir -p config
docker run -d --name picolb --restart unless-stopped \
-p 80:80 -p 443:443 \
-v "$PWD/config:/config" \
-v picolb-data:/data \
garfieldwtf/picolb
Docker Compose:
services:
picolb:
image: garfieldwtf/picolb
restart: unless-stopped
ports: ["80:80", "443:443"]
volumes:
- ./config:/config
- picolb-data:/data
volumes:
picolb-data:
Save as config/picolb.json. It serves blog.example.com from two backends (the first gets twice the traffic),
with a third as a standby, and gets a certificate automatically:
{
"entryPoints": {
"web": { "address": ":80", "redirect": { "to": "websecure", "permanent": true } },
"websecure": { "address": ":443", "tls": true }
},
"acme": { "email": "[email protected]", "acceptTerms": true },
"logs": { "dir": "off" },
"http": {
"routers": {
"blog": { "rule": "Host(`blog.example.com`)", "service": "blog" }
},
"services": {
"blog": {
"loadBalancer": {
"servers": [
{ "url": "http://app1:3000", "weight": 2 },
{ "url": "http://app2:3000" },
{ "url": "http://app3:3000", "passive": true }
],
"healthCheck": { "path": "/", "interval": "10s", "timeout": "3s" }
}
}
}
}
}
No health page on your app? Just use /. For automatic certificates, the domain must point at this server and ports
80 and 443 must reach the container from the internet. The dashboard's Config tab can generate a config like this for you.
/config | Holds picolb.json (and picolb.json.bak when the dashboard changes it). Mount the folder, not the single file: the dashboard replaces the file atomically, which a single-file mount doesn't allow. Edits reload within 2 seconds; docker kill -s HUP picolb reloads at once. |
/data | The working directory. Automatic certificates are stored in /data/acme: keep it on a volume so they survive re-creation (CAs limit how often you can request them). |
| Backends | 127.0.0.1 inside the container is the container itself. Use the container name on a shared Docker network (http://myapp:3000), or the host's address. |
| Dashboard | Off by default. Add "api": {"address": ":8081", "users": ["admin:{PLAIN}change-me"]} and publish -p 8081:8081. A login is required for live editing. The Config tab can hash the password for you. |
| Self-signed backends | For https:// backends with a self-signed certificate, set "serversTransport": {"insecureSkipVerify": true} on the service. |
| Health check | Built in (/picolb -healthcheck, every 30 seconds), shown by docker ps. |
| Logs | docker logs picolb. The starter config sets "logs": {"dir": "off"}, so no log files are kept in the container. To keep one file per domain, remove that line and mount -v /var/log/picolb:/var/log/picolb. |
| Config location | PICOLB_CONFIG (default /config/picolb.json). |
| Stopping | docker stop sends SIGTERM; in-flight requests get up to 10 seconds. |
The container runs as root by default, so mounted folders are writable and ports 80/443 just work. To run unprivileged with a read-only root file system:
mkdir -p config data && sudo chown -R 65532:65532 config data
docker run -d --name picolb --restart unless-stopped --read-only --user 65532:65532 \
-p 80:80 -p 443:443 -v "$PWD/config:/config" -v "$PWD/data:/data" garfieldwtf/picolb
Only /config and /data are ever written, so --read-only is safe. The mounted folders must belong to that user.
The binary in this image is the same static binary you get from building the project with
CGO_ENABLED=0 go build.
Content type
Image
Digest
sha256:e0636476d…
Size
3.5 MB
Last updated
3 days ago
docker pull garfieldwtf/picolb