HUB
Sign inSign up
picolb logo

garfieldwtf/picolb

By garfieldwtf

•Updated 3 days ago

Tiny single-binary load balancer and reverse proxy, Traefik-style rules. FROM scratch, ~9 MB.

Image
0

63

garfieldwtf/picolb repository overview

⁠PicoLB

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.

  • Routes by domain and path (Host(...), PathPrefix(...), and more), with priorities
  • Load balancing: weights, standby servers, sticky sessions, health checks, automatic failover
  • HTTPS with automatic certificates (ZeroSSL or Let's Encrypt) or your own files, HTTP to HTTPS redirect
  • Middlewares: compression, rate limit, basic auth, security headers, redirects, path rewriting, IP allow lists, and more
  • A web dashboard with a config builder, and live editing with a review and confirm step
  • Hot reload: edit the config file and it applies within 2 seconds, without dropping connections
  • Raw TCP routing, Prometheus metrics, styled error pages, access log, one log file per domain

It is not all of Traefik. Check the "What is not implemented" list in the project README before relying on it.

⁠Quick start

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/

⁠Use it for real

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:
⁠A first config

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.

⁠Things to know

/configHolds 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.
/dataThe 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).
Backends127.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.
DashboardOff 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 backendsFor https:// backends with a self-signed certificate, set "serversTransport": {"insecureSkipVerify": true} on the service.
Health checkBuilt in (/picolb -healthcheck, every 30 seconds), shown by docker ps.
Logsdocker 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 locationPICOLB_CONFIG (default /config/picolb.json).
Stoppingdocker stop sends SIGTERM; in-flight requests get up to 10 seconds.
⁠Hardening

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.

⁠Source and documentation

The binary in this image is the same static binary you get from building the project with CGO_ENABLED=0 go build.

Tag summary

Content type

Image

Digest

sha256:e0636476d…

Size

3.5 MB

Last updated

3 days ago

docker pull garfieldwtf/picolb