You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Reverse proxy support is mainly useful when public or LAN clients reach the stack on different ports than the backend listeners. The server still runs its own TLS listeners for both HTTPS and MQTT/TLS; the proxy forwards traffic to those listeners. I do not use a reverse proxy for my own setup, so please report any issues.
3
+
Reverse proxy support is mainly useful when public or LAN clients reach the stack on different ports than the backend listeners, or when you already run a proxy (Caddy, Traefik, nginx) that owns your TLS certificates. I do not use a reverse proxy for my own setup, so please report any issues.
4
4
5
-
## Supported Layout
5
+
Whatever endpoint a vacuum or the Roborock app connects to **must present a valid, trusted TLS certificate** — vacuums refuse to connect otherwise. That endpoint can be the server itself or the proxy in front of it; the rest of this page is about choosing which one terminates TLS.
6
6
7
-
Use this when:
7
+
## Advertised Ports
8
8
9
-
- HTTPS reaches the proxy on `443`, then forwards to the stack HTTPS listener such as `555`
10
-
- MQTT/TLS reaches a TCP/stream proxy on `8883`, then forwards to the stack MQTT/TLS listener such as `8881`
11
-
- the proxy preserves the original `Host` header
12
-
13
-
Example:
9
+
Use these when the proxy maps public ports to different backend listener ports. The server binds the `*_port` listeners but advertises the `advertised_*` ports to the Roborock app, vacuums, and Home Assistant.
14
10
15
11
```toml
16
12
[network]
@@ -21,28 +17,79 @@ bind_host = "0.0.0.0"
21
17
https_port = 555
22
18
mqtt_tls_port = 8881
23
19
24
-
# Public ports advertised to the Roborock app, vacuums, and Home Assistant.
20
+
# Public ports advertised to clients.
25
21
advertised_https_port = 443
26
22
advertised_mqtt_tls_port = 8883
27
23
```
28
24
29
-
With that config the server listens on `https://*:555`and `ssl://*:8881`, but responses advertise:
25
+
With that config the server listens on `*:555`/ `*:8881`, but responses advertise:
30
26
31
27
-`https://api-roborock.example.com`
32
28
-`ssl://api-roborock.example.com:8883`
33
29
34
-
## Proxy Requirements
30
+
## TLS Termination Modes
31
+
32
+
### `local_tls` (default) — the server terminates TLS
33
+
34
+
The server runs its own TLS listeners; the proxy forwards encrypted traffic to them. The proxy must preserve the original `Host` header. For MQTT, use a TCP/stream proxy (a normal HTTP location is not enough because MQTT is not HTTP).
35
+
36
+
If you already manage certificates in the proxy, point the server at the same certificate chain so both present an identical, valid cert:
37
+
38
+
```toml
39
+
[network]
40
+
listener_mode = "local_tls"
41
+
42
+
[tls]
43
+
mode = "provided"
44
+
cert_file = "/path/to/proxy/fullchain.pem"
45
+
key_file = "/path/to/proxy/privkey.pem"
46
+
```
47
+
48
+
### `external_tls` — the proxy terminates TLS
35
49
36
-
For HTTPS admin/API traffic, the proxy must forward the original `Host` header unchanged:
50
+
The proxy terminates TLS and forwards plain HTTP/TCP to the server, which holds no certificates at all. The proxy is responsible for presenting a valid cert to clients.
37
51
38
-
```text
39
-
Host: $host
52
+
```toml
53
+
[network]
54
+
listener_mode = "external_tls"
55
+
56
+
[tls]
57
+
# No certificate material is required in this mode.
58
+
mode = "provided"
59
+
```
60
+
61
+
Requirements:
62
+
63
+
- HTTPS: the proxy terminates TLS, preserves the original `Host` header, and forwards plain HTTP to `https_port`.
64
+
- MQTT: a **stream / layer-4** proxy must terminate TLS with a valid cert on the public MQTT port and forward plain TCP to `mqtt_tls_port`. An HTTP reverse proxy alone cannot do this.
65
+
-`tls.mode` must be `"provided"`. `external_tls` never issues or renews certificates, so `cloudflare_acme` is rejected to avoid a silent no-op.
66
+
67
+
> **Do not expose the backend ports publicly.** In `external_tls` the server speaks plain, unencrypted HTTP and MQTT on `https_port` / `mqtt_tls_port`. Bind them to localhost or an internal Docker network reachable only by the proxy — never publish them to the host or the internet. With the bundled `compose.yaml`, the `ports:` mappings publish the backend ports; remove or restrict them so only the proxy reaches the server. If you run the proxy in the same Compose project, drop the `ports:` entries entirely and reference the service by name (e.g. `roborock-local-server:555`).
68
+
>
69
+
> The Docker healthcheck defaults to `https`. In `external_tls` set `ROBOROCK_SERVER_HEALTHCHECK_SCHEME=http` so it probes the plain-HTTP listener.
70
+
71
+
Example Caddy config (HTTPS via the standard reverse proxy, MQTT via the [layer4 plugin](https://github.com/mholt/caddy-l4)):
72
+
73
+
```caddyfile
74
+
api-roborock.example.com {
75
+
reverse_proxy roborock-local-server:555
76
+
}
40
77
```
41
78
42
-
For MQTT/TLS, use TCP or stream proxying. A normal HTTP reverse proxy location is not enough because MQTT is not HTTP. The proxy must forward raw TCP from the public MQTT/TLS port to `mqtt_tls_port`.
79
+
```caddyfile
80
+
# layer4 app (Caddy JSON / global block) terminating MQTT TLS on 8883
81
+
:8883 {
82
+
route {
83
+
tls
84
+
proxy {
85
+
upstream roborock-local-server:8881
86
+
}
87
+
}
88
+
}
89
+
```
43
90
44
91
## What Is Not Supported
45
92
46
93
Path-prefix hosting is not supported. The Roborock protocol and the admin API expect the stack at the hostname root, for example `/region`, `/api/...`, and `/admin`.
47
94
48
-
Plain HTTP backends are not supported. If you already manage certificates in a proxy, point `tls.cert_file` and `tls.key_file` at those certificate files so the backend TLS listener uses the same certificate chain.
95
+
`external_tls` is intended for Docker / standalone deployments. The Home Assistant add-on always terminates its own TLS and does not expose this option.
0 commit comments