Skip to content

Commit b0d97cd

Browse files
CodeShellDevCodeShellDev
committed
update readme
1 parent 042bc88 commit b0d97cd

6 files changed

Lines changed: 184 additions & 41 deletions

File tree

‎.github/templates/README.template.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,42 @@ Environment variables:
8181
{{{ #://examples/config/config.env }}}
8282
```
8383

84+
## Hosts Configuration
85+
86+
The `hosts` section defines all machines, VMs, containers, or Docker services that WoL Redirect can wake up. Each host entry may have several optional or required fields depending on its type.
87+
88+
| Field | Type | Required | Description |
89+
| -------------- | ------- | ------------------------ | ------------------------------------------------------------------------------- |
90+
| `ip` | string | Yes | The IP address of the host. Required for all types. |
91+
| `mac` | string | Required for PHYSICAL | MAC address for Wake-on-LAN. Only needed for physical hosts. |
92+
| `id` | string | Required for VIRTUAL | Identifier for virtual machines or LXCs. |
93+
| `virtIP` | string | Optional | IP of the VM/LXC for the wake API. Defaults to `ip`. |
94+
| `startupTime` | number | Optional | Seconds to wait after starting before forwarding traffic. |
95+
| `url` | string | Optional | Override the default helper URL for this host. |
96+
| `docker` | object | Required for DOCKER type | Docker-specific settings. See below. |
97+
| `docker: true` | boolean | Optional | Can be set to `true` to mark a host as DOCKER type without additional settings. |
98+
99+
## Docker Sub-Object
100+
101+
| Field | Type | Required | Description |
102+
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
103+
| `queryPattern` | string | Optional | Template used to build the query for WoL Dockerized. Falls back to `ENV.woldQueryPattern`. |
104+
| `url` | string | Optional | Override URL for Docker wake API. Defaults to `http://${host.ip}:${ENV.woldPort}/wake`. |
105+
106+
## Host Type Inference
107+
108+
- **PHYSICAL** → has `mac` and `ip`
109+
- **VIRTUAL** → has `id`
110+
- **DOCKER** → has `docker` object or `docker: true`
111+
112+
## Notes on Optional Overrides
113+
114+
- `url` can override default helper URLs for PHYSICAL, VIRTUAL, or DOCKER hosts.
115+
- `virtIP` can override the IP used by virtual helper services.
116+
- `docker.queryPattern` can override the global `ENV.woldQueryPattern`.
117+
- `startupTime` allows per-host delay before forwarding traffic.
118+
- The execution order of hosts in a route determines the startup sequence.
119+
84120
## Advanced Setups
85121

86122
WoL Redirect supports two main scenarios depending on how your services are hosted.

‎examples/config/config.env‎

Lines changed: 90 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,90 @@
1-
CLIENT_ID=CLIENT_ID
2-
CLIENT_SECRET=CLIENT_SECRET
3-
4-
# Authentik setup
5-
AUTH_URL=https://authentication.mydomain.com/application/o/authorize/
6-
TOKEN_URL=https://authentication.mydomain.com/application/o/token/
7-
REDIRECT_URL=https://wol-redirect.mydomain.com/auth/callback/
8-
RESOURCE_URL=https://authentication.mydomain.com/application/o/userinfo/
9-
LOGOUT_URL=https://authentication.mydomain.com/application/o/wol-red/end-session/
10-
11-
SESSION_KEY=MY_SESSION_KEY # generate this with openssl
12-
SCOPE=openid
1+
############################
2+
# Core Application Settings
3+
############################
4+
5+
# Path to the service mapping configuration file
6+
CONFIG_PATH=/app/config/mapping.json
7+
8+
# Port WoL Redirect listens on
9+
PORT=6789
10+
11+
# Log level: trace | debug | info | warn | error | fatal
12+
LOG_LEVEL=info
13+
14+
# Expose logs via the UI or HTTP endpoint
15+
EXPOSE_LOGS=true
16+
17+
18+
############################
19+
# Session & Security
20+
############################
21+
22+
# Secret key used to sign sessions (REQUIRED)
23+
# Generate a long random string
24+
SESSION_KEY=change-me-to-a-random-secret
25+
26+
27+
############################
28+
# Redis Configuration
29+
############################
30+
31+
# Redis hostname or service name
32+
REDIS_HOST=redis
33+
34+
# Redis port
35+
REDIS_PORT=6379
36+
37+
# Redis username (usually "default")
38+
REDIS_USER=default
39+
40+
# Redis password (use long secure password)
41+
REDIS_PASSWORD=
42+
43+
44+
############################
45+
# Wake-on-LAN / Helper Services
46+
############################
47+
48+
# Default query pattern used to match WoL services
49+
WOLD_QUERY_PATTERN=
50+
51+
# Base URL of default your WoL Client helper
52+
# Example: http://wol-client:5555/wake
53+
WOL_URL=
54+
55+
# Default port used by WoL Dockerized helper
56+
WOLD_PORT=7777
57+
58+
# Default port used by virtualization helper (VMs / LXCs / hypervisors)
59+
VIRTUAL_PORT=9999
60+
61+
62+
############################
63+
# OAuth Configuration
64+
############################
65+
66+
# Enable or disable OAuth authentication
67+
USE_OAUTH=true
68+
69+
# OAuth authorization endpoint
70+
AUTHORIZATION_URL=
71+
72+
# OAuth resource / userinfo endpoint
73+
RESOURCE_URL=
74+
75+
# OAuth logout endpoint
76+
LOGOUT_URL=
77+
78+
# OAuth token endpoint
79+
TOKEN_URL=
80+
81+
# Redirect URL registered with your OAuth provider
82+
# Example: https://wol-red.mydomain.com/auth/callback
83+
REDIRECT_URL=
84+
85+
# OAuth client credentials
86+
CLIENT_ID=
87+
CLIENT_SECRET=
88+
89+
# OAuth scopes
90+
SCOPE=openid profile

‎examples/config/docker.mapping.json‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,19 @@
11
{
22
"hosts": {
33
"docker-server": {
4-
"ip": "192.168.5.10",
5-
"docker": true
4+
"ip": "192.168.1.10",
5+
"docker": {
6+
"queryPattern": "{{HOSTNAME}}"
7+
}
68
}
79
},
810
"routes": {
9-
"docker": {
11+
"docker-only": {
1012
"route": ["docker-server"]
1113
}
1214
},
1315
"records": {
14-
"jellyfin.mydomain.com": "docker",
15-
"*.mydomain.com": "docker"
16+
"jellyfin.mydomain.com": "docker-only",
17+
"*.mydomain.com": "docker-only"
1618
}
1719
}

‎examples/config/mapping.json‎

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,19 @@
11
{
2-
"hosts": {
3-
"server-1": {
4-
"ip": "192.168.1.1",
5-
"mac": "XX:XX:XX:XX:XX:XX",
6-
"startupTime": 60
7-
}
8-
},
9-
"routes": {
10-
"server-1": {
11-
"route": ["server-1"]
12-
}
13-
},
14-
"records": {
15-
"*.mydomain.com": "server-1"
16-
}
2+
"hosts": {
3+
"server": {
4+
"ip": "192.168.1.1", // REQUIRED: Host IP
5+
"mac": "XX:XX:XX:XX:XX:XX", // REQUIRED for PHYSICAL type
6+
"startupTime": 60, // Optional: seconds to wait after wake
7+
"url": "http://custom-wol:7777
8+
" // Optional: override default ENV.wolURL
179
}
10+
},
11+
"routes": {
12+
"server-only": {
13+
"route": ["server"]
14+
}
15+
},
16+
"records": {
17+
"*.mydomain.com": "server-only"
18+
}
19+
}

‎examples/config/virtual-docker.mapping.json‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
{
2+
"hosts": {
3+
"hypervisor": {
4+
"ip": "192.168.1.1",
5+
"mac": "XX:XX:XX:XX:XX:XX",
6+
"startupTime": 40
7+
},
8+
"lxc": {
9+
"ip": "192.168.1.1",
10+
"id": "100",
11+
"virtIP": "10.0.0.10",
12+
"startupTime": 10
13+
},
14+
"docker-server": {
15+
"ip": "10.0.0.10",
16+
"docker": {
17+
"queryPattern": "{{HOSTNAME}}"
18+
}
19+
}
20+
},
21+
"routes": {
22+
"hypervisor-lxc-docker": {
23+
"route": ["hypervisor", "lxc", "docker-server"]
24+
}
25+
},
26+
"records": {
27+
"*.mydomain.com": "hypervisor-lxc-docker"
28+
}
29+
}

‎examples/config/virtual.mapping.json‎

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,23 +5,19 @@
55
"mac": "XX:XX:XX:XX:XX:XX",
66
"startupTime": 40
77
},
8-
"lxc": {
9-
"ip": "192.168.1.1",
10-
"id": "100",
11-
"startupTime": 10
12-
},
138
"vm": {
149
"ip": "192.168.1.1",
1510
"id": "200",
16-
"startupTime": 10
11+
"virtIP": "192.168.1.20",
12+
"startupTime": 15
1713
}
1814
},
1915
"routes": {
20-
"hypervisor-lxc": {
21-
"route": ["hypervisor", "lxc"]
16+
"hypervisor-vm": {
17+
"route": ["hypervisor", "vm"]
2218
}
2319
},
2420
"records": {
25-
"*.mydomain.com": "hypervisor-lxc"
21+
"*.mydomain.com": "hypervisor-vm"
2622
}
2723
}

0 commit comments

Comments
 (0)