Python-roborock · DeRus0 · Jul 18, 2026 · Jul 20, 2026 · Jul 20, 2026 · Jul 29, 2026
diff --git a/README.md b/README.md
@@ -1,68 +1,42 @@
 # Roborock Local Server
-
 [![GHCR][badge-ghcr]][link-ghcr]
 
-The best way to support this project is the next time you are buying a Roborock device come back here and use one of my affiliate links where I will receive a commission.
-
-[![Amazon Affiliate][badge-amazon]][link-amazon]
-[![Roborock Affiliate][badge-roborock-affiliate]][link-roborock-affiliate]
-
-You can also support via BMAC or paypal:
-
-[![Buy Me a Coffee][badge-bmac]][link-bmac]
-[![PayPal][badge-paypal]][link-paypal]
+## Introduction
 
-Roborock Local Server is a private Roborock HTTPS and MQTT stack you run on your own system.
+**Roborock Local Server** is a private, self-hosted alternative to Roborock's cloud infrastructure. This project enables you to run a complete HTTPS and MQTT stack on your own network, giving you full control over your Roborock vacuum's communication and operations without relying on external cloud services. While the vacuum can still connect to some Roborock's owned services, this stack provides all necessary functionality for your vacuum to work with almost no compromise. 
 
-This service is meant to stay private. Point your own DNS at your server's LAN IP. If you want this to work away from your home network, the server does handle auth and lets you disable new devices from connecting. BUT there is ALWAYS a risk when you make a self-hosted service publicly accessible, so please only do it if you know what you are doing. If your workflow is fine with local-only access, that will always be better. If you find any vulnerabilities, please let me know.
+After installation, you can block internet access entirely and the vacuum will continue to function on your local network. The stack is also fully compatible with Home Assistant and the Roborock app, so you can seamlessly repoint them to your local server for integrated control.
 
-## Container Image
+## Support
+If you appreciate this project, the best way to support it is by using my affiliate links when purchasing a Roborock device. It helps support development at no cost to you.
 
-Published image:
+[![Amazon Affiliate][badge-amazon]][link-amazon] [![Roborock Affiliate][badge-roborock-affiliate]][link-roborock-affiliate]
 
-```sh
-docker pull ghcr.io/python-roborock/local_roborock_server:latest
-```
+Alternatively, you can also donate directly to support the project:
 
-## Contributing
+[![Buy Me a Coffee][badge-bmac]][link-bmac] [![PayPal][badge-paypal]][link-paypal]
 
-If you would like to contribute there are a few ways that would be great!
 
-1. Code is always welcome that you have fully tested.
-2. Video walkthroughs of how to actually set this up would be great.
-3. Documentation. I hate documentation and it's something I find myself often pushing off to AI so that I can focus more on the harder problems. But I find that human written documentation always 'feels' better.
+For those who want to contribute in other ways, here are things that would be helpful:
 
-## Requirements
-
-- a domain you control
-- a place to run the stack on your LAN
-- either Docker Compose or a Home Assistant installation that supports add-ons
-- a second machine for onboarding later
-- a Cloudflare API token with DNS edit access for the zone if you want automatic certificate renewal
+- Tested code contributions are always welcome.
+- Video walkthroughs showing how to set this up would be greatly appreciated.
+- Documentation is also helpful. I often put it off to AI so I can focus on the harder problems, but human-written documentation always feels better.
+- Lastly, if you have a vacuum that is not yet tested with this stack, testing it and reporting your results would be very helpful to the community. See [Tested Vacuums](tested_vacuums.md) for more information.
 
 ## Getting Started
 
-Start here if this is your first time setting up the stack:
-
-1. [Installation](docs/installation.md) for the shared requirements, network setup, and Docker Compose install path.
-2. [Home Assistant](docs/home_assistant.md) if you want to install the stack as a Home Assistant add-on instead of Docker Compose.
-3. [Cloudflare setup](docs/cloudflare_setup.md) if you want Cloudflare DNS-01 auto-renew for certificates.
-4. [Onboarding](docs/onboarding.md) to pair a vacuum from a second machine after the server is running.
-5. [Updating](docs/updating.md) if you already have an install and are moving to a newer stable release.
-
-Before choosing a certificate path, check [Tested vacuums](docs/tested_vacuums.md). Different models do not all accept the same certificate chains. For most users, start with ZeroSSL. Use Actalis mainly for older vacuums or models that are already known to trust that chain more reliably.
-
-Additional docs:
+For the installation process, go to [installation.md](installation.md). That guide walks through the initial setup, required components, and the order in which to configure each part of the stack so you can get up and running with minimal friction.
 
-- [Docs index](docs/index.md)
-- [Known limitations](docs/known_limitations.md)
-- [Tested vacuums](docs/tested_vacuums.md)
-- [Home Assistant](docs/home_assistant.md) for the add-on install path and Home Assistant integration rewiring
-- [Using the Roborock App](docs/roborock_app.md)
-- [Updating](docs/updating.md)
-- [Custom MQTT](docs/custom_mqtt.md)
-- [Custom certificate management](docs/custom_cert_management.md)
+## Additional docs
 
+- [Tested vacuums](docs/tested_vacuums.md) - List of vacuums that have been tested with this stack
+- [Known limitations](docs/known_limitations.md) - Information about known issues with specific vacuum models
+- [Home Assistant](docs/home_assistant.md) - for the add-on install path and Home Assistant integration rewiring
+- [Repointing the Roborock App](docs/roborock_app.md) - How to repoint the Roborock app to your local server
+- [Updating](docs/updating.md) - Procedures for updating an existing installation
+- [Custom MQTT](docs/custom_mqtt.md) - Instructions for using a custom MQTT broker
+- [Custom certificate management](docs/custom_cert_management.md) - Guidance for using your own certificate files
 
 
 ## Acknowledgements

diff --git a/docs/docker_compose.md b/docs/docker_compose.md
@@ -0,0 +1,91 @@
+# Docker Compose installation
+
+This page only covers the Docker Compose-specific parts. It is assumed you have already completed the shared setup steps in [installation.md](installation.md) and have a working hostname and DNS.
+
+> Advanced users can use the container image directly from:
+`ghcr.io/python-roborock/local_roborock_server`
+
+ ### Additional Requirements
+- Docker with `docker compose`
+- Python
+- [uv](https://docs.astral.sh/uv/getting-started/installation/)
+
+### Steps
+1. Clone this repository:
+
+   ```bash
+   git clone https://github.com/Python-roborock/local_roborock_server
+   cd local_roborock_server
+   ```
+
+2. Install the project dependencies:
+
+   ```bash
+   uv sync
+   ```
+
+3. Run the setup wizard:
+
+   ```bash
+   uv run roborock-local-server configure
+   ```
+
+ * The wizard asks for your:
+   - `stack_fqdn` which you have set up in [Shared Setup](installation.md#network-setup)
+   - HTTPS and MQTT TLS ports (it is recommended to keep the defaults unless you have a specific reason to change them)
+   - Whether to use the embedded MQTT broker or your own (see [Custom MQTT](custom_mqtt.md))
+   - Whether to use Cloudflare DNS-01 auto-renew
+      If yes, the setup ask for:
+      - The `ACME domain` (domain for the certificate to be issued) and `account email` (any email you want to use for ACME account registration)
+      - Whether to use ZeroSSL or Actalis.
+         - If you chose Actalis, the setup asks for your Actalis `EAB KID` and `EAB HMAC key`. 
+      - Your `Cloudflare API token` you created earlier.
+   - An admin password you will use to log in to the admin dashboard
+   - A Home Assistant/app login email and 6-digit PIN which can be used to repoint Home Assistant or the Roborock app to your local server.
+
+ The wizard then creates `config.toml`, generates `admin.password_hash` and `admin.session_secret`. Depending whether or not you chose Cloudflare it writes `secrets/cloudflare_token` and if you set your `acme_server = actalis`, it also writes `secrets/acme_eab_kid` and `secrets/acme_eab_hmac_key`.
+
+> If you chose external MQTT, fill in `broker.host` in `config.toml` before starting the stack.
+
+> If you skipped Cloudflare, put your certificate files in `data/certs/fullchain.pem` and `data/certs/privkey.pem`. This is the path to use when your vacuum works better with a certificate chain you manage yourself. See [Custom certificate management](custom_cert_management.md).
+
+4. Starting the container:
+   If you set your custom ports during the setup, set matching Docker Compose variables before you start the stack so the published ports stay aligned. For example:
+
+   ```bash
+   ROBOROCK_SERVER_HTTPS_PORT=8443
+   ROBOROCK_SERVER_MQTT_TLS_PORT=9443
+   ```
+
+   In PowerShell:
+
+   ```powershell
+   $env:ROBOROCK_SERVER_HTTPS_PORT = "8443"
+   $env:ROBOROCK_SERVER_MQTT_TLS_PORT = "9443"
+   ```
+
+   > In custom setups where decided to run a reverse proxy, keep `network.https_port` and `network.mqtt_tls_port` set to the backend listener ports and use `network.advertised_https_port` / `network.advertised_mqtt_tls_port` for the public ports.
+
+After all is done, you can start the stack with:
+ ```bash
+   docker compose up -d --build
+   ```
+
+## Test your installation
+To test your installation, open a browser and go to `https://api-roborock.example.com:555/admin` (or your custom HTTPS port). You should see the admin dashboard login page.
+
+If you chose Cloudflare DNS-01 auto-renew, it may take a few minutes for the certificate to be issued. If the page does not load after a few minutes, check that the DNS resolves correctly and the stack is running: 
+
+```bash
+docker compose ps #check if the stack is running
+docker compose logs -f roborock-local-server #check the logs for errors
+``` 
+
+## Next Steps
+- [Installation - After the Stack Starts](installation.md#after-the-stack-starts) for post-start steps.
+
+## Related Guides
+- [Updating](updating.md) for upgrading an existing instal
+- [Home Assistant](home_assistant.md#repoint-the-home-assistant-roborock-integration) if you want to repoint the Home Assistant Roborock integration to your local stack
+- [Onboarding](onboarding.md) for pairing a new vacuum
+- [Repointing the Roborock App](roborock_app.md) if you want to point the official app at your local stack