DOCKER.md (3511B)
1 # UDPHOLE Docker 2 3 Run udphole as a Docker container. 4 5 ## Quick Start 6 7 ```bash 8 docker run -p 6379:6379 -p 7000-7999:7000-7999/udp finwo/udphole 9 ``` 10 11 The entrypoint always adds `--no-daemonize` to ensure the container stays running. 12 13 ## Environment Variables 14 15 | Variable | Default | Description | 16 |----------|---------|-------------| 17 | `API_PORT` | `6379` | TCP port for the RESP2 API server | 18 | `UDP_PORTS` | `7000-7999` | UDP port range for UDP sockets | 19 | `LOG_LEVEL` | `info` | Log verbosity: fatal, error, warn, info, debug, trace | 20 | `API_ADMIN_USER` | `admin` | Username for admin user | 21 | `API_ADMIN_PASS` | `supers3cret` | Password for admin user | 22 | `CLUSTER` | | Comma-separated list of cluster node addresses (enables cluster mode, e.g., `tcp://user:pass@host1:6379,tcp://user:pass@host2:6379`) | 23 24 ## Auto-generated Config 25 26 If no config file is mounted, the container auto-generates `/etc/udphole.conf` from environment variables: 27 28 ```ini 29 [udphole] 30 ports = 7000-7999 31 listen = :6379 32 33 [user:admin] 34 permit = * 35 secret = supers3cret 36 ``` 37 38 ### Custom Config 39 40 Mount your own config file to override defaults: 41 42 ```bash 43 docker run -p 6379:6379 -p 7000-7999:7000-7999/udp \ 44 -v /path/to/udphole.conf:/etc/udphole.conf:ro \ 45 finwo/udphole 46 ``` 47 48 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). 49 50 ### Listen Address Formats 51 52 The `listen` directive supports multiple addresses: 53 54 | Format | Description | 55 |--------|-------------| 56 | `:6379` | All interfaces, port 6379 | 57 | `6379` | All interfaces, port 6379 | 58 | `localhost:6379` | Loopback only | 59 | `192.168.1.1:6379` | Specific IPv4 address | 60 | `tcp://:6379` | Explicit TCP, all interfaces | 61 | `tcp://localhost:6379` | Explicit TCP, loopback | 62 | `unix:///tmp/udphole.sock` | Unix socket | 63 64 Multiple listen addresses can be specified: 65 66 ```ini 67 [udphole] 68 listen = :6379 69 listen = 192.168.1.1:6380 70 listen = unix:///tmp/udphole.sock 71 ``` 72 73 ## Cluster Mode 74 75 To run in cluster mode, set the `CLUSTER` environment variable with comma-separated node addresses: 76 77 ```bash 78 docker run -p 6379:6379 -p 7000-7999:7000-7999/udp \ 79 -e CLUSTER="tcp://user:pass@192.168.1.10:6379,tcp://user:pass@192.168.1.11:6379" \ 80 finwo/udphole 81 ``` 82 83 This generates: 84 85 ```ini 86 [udphole] 87 ports = 7000-7999 88 listen = :6379 89 cluster = tcp://user:pass@192.168.1.10:6379 90 cluster = tcp://user:pass@192.168.1.11:6379 91 92 [user:admin] 93 permit = * 94 secret = supers3cret 95 ``` 96 97 ### Cluster Node Address Formats 98 99 | Format | Description | 100 |--------|-------------| 101 | `tcp://host:port` | TCP connection | 102 | `tcp://user:pass@host:port` | TCP with authentication | 103 | `unix:///path/to/socket` | Unix socket | 104 105 ## Docker Compose 106 107 ```yaml 108 services: 109 udphole: 110 image: finwo/udphole 111 ports: 112 - "6379:6379" 113 - "7000-7999:7000-7999/udp" 114 environment: 115 - API_PORT=6379 116 - UDP_PORTS=7000-7999 117 - LOG_LEVEL=info 118 - API_ADMIN_USER=admin 119 - API_ADMIN_PASS=supers3cret 120 healthcheck: 121 test: ["CMD", "nc", "-z", "localhost", "6379"] 122 interval: 10s 123 timeout: 5s 124 retries: 3 125 ``` 126 127 ## Healthcheck 128 129 The container includes a healthcheck using `nc` to verify the API port is listening: 130 131 ```bash 132 nc -z localhost 6379 133 ``` 134 135 ## Architecture 136 137 The container is available for: 138 - `linux/amd64` 139 - `linux/arm64/v8` (e.g., Raspberry Pi 4+, M1 Mac) 140 - `linux/riscv64` 141 142 Docker automatically selects the correct variant for your host architecture.