finwo/udphole repository overview

⁠UDPHOLE Docker

Run udphole as a Docker container.

⁠Quick Start

docker run -p 6379:6379 -p 7000-7999:7000-7999/udp finwo/udphole

The entrypoint always adds --no-daemonize to ensure the container stays running.

⁠Environment Variables

⁠Auto-generated Config

If no config file is mounted, the container auto-generates /etc/udphole.conf from environment variables:

[udphole]
ports = 7000-7999
listen = :6379

[user:admin]
permit = *
secret = supers3cret

⁠Custom Config

Mount your own config file to override defaults:

docker run -p 6379:6379 -p 7000-7999:7000-7999/udp \
  -v /path/to/udphole.conf:/etc/udphole.conf:ro \
  finwo/udphole

Note: Even with cluster fields defined in a mounted config, you must set CLUSTER to any value to run in cluster mode (the entrypoint uses this to decide between daemon and cluster commands).

⁠Listen Address Formats

The listen directive supports multiple addresses:

Multiple listen addresses can be specified:

[udphole]
listen = :6379
listen = 192.168.1.1:6380
listen = unix:///tmp/udphole.sock

⁠Cluster Mode

To run in cluster mode, set the CLUSTER environment variable with comma-separated node addresses:

docker run -p 6379:6379 -p 7000-7999:7000-7999/udp \
  -e CLUSTER="tcp://user:[email protected]:6379,tcp://user:[email protected]:6379" \
  finwo/udphole

This generates:

[udphole]
ports = 7000-7999
listen = :6379
cluster = tcp://user:[email protected]:6379
cluster = tcp://user:[email protected]:6379

[user:admin]
permit = *
secret = supers3cret

⁠Cluster Node Address Formats

⁠Docker Compose

services:
  udphole:
    image: finwo/udphole
    ports:
      - "6379:6379"
      - "7000-7999:7000-7999/udp"
    environment:
      - API_PORT=6379
      - UDP_PORTS=7000-7999
      - LOG_LEVEL=info
      - API_ADMIN_USER=admin
      - API_ADMIN_PASS=supers3cret
    healthcheck:
      test: ["CMD", "nc", "-z", "localhost", "6379"]
      interval: 10s
      timeout: 5s
      retries: 3

⁠Healthcheck

The container includes a healthcheck using nc to verify the API port is listening:

nc -z localhost 6379

⁠Architecture

The container is available for:

• linux/amd64
• linux/arm64/v8 (e.g., Raspberry Pi 4+, M1 Mac)
• linux/riscv64

Docker automatically selects the correct variant for your host architecture.