remove mitm, add onboarding flow, add basic docs

Author: Lash-L

.github/workflows/docs.yml

@@ -0,0 +1,64 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - .github/workflows/docs.yml
+      - docs/**
+      - mkdocs.yml
+      - pyproject.toml
+      - uv.lock
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+  pages: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version-file: pyproject.toml
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Install project
+        run: uv sync --locked --extra dev
+
+      - name: Build docs
+        run: uv run mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -4,5 +4,6 @@ __pycache__/
 *.pyd
 .pytest_cache/
 data/
+site/
 secrets/
 config.toml

Dockerfile

@@ -18,8 +18,8 @@ WORKDIR /app
 
 COPY . /app
 
-RUN pip install --no-cache-dir "/app[mitm]"
+RUN pip install --no-cache-dir /app
 
-EXPOSE 443 8883 8081 51820/udp
+EXPOSE 443 8883
 
 CMD ["roborock-local-server", "serve", "--config", "/app/config.toml"]

README.md

@@ -47,14 +47,9 @@ Pick one hostname under your domain, for example `roborock.example.com`.
 - Cloudflare is only used for DNS-01 certificate issuance. It does not need to proxy traffic to your server.
 
 The vacuum needs to be able to hit your server on ports 443/tcp and 8883/tcp.
-If you use iPhone MITM intercept, expose 8081/tcp for the mitmweb UI (logs + WireGuard QR).
-When running in Docker, prefer the Admin "Open WireGuard Config (Docker-safe)" link over mitmweb's QR if the QR shows a container-only endpoint.
-The Admin MITM panel also provides an "Open WireGuard QR" code generated from the Docker-safe config.
 
 - `443/tcp` for HTTPS
 - `8883/tcp` for MQTT over TLS
-- `8081/tcp` for mitmweb (optional, MITM only, access by IP not hostname)
-- `51820/udp` for WireGuard MITM tunnel traffic
 
 ## Project Layout
 
@@ -83,34 +78,33 @@ cd roborock_local_server
 uv sync
 ```
 
-3. Generate an admin password hash.
+3. Run the setup wizard.
 
 ```bash
-uv run roborock-local-server hash-password
+uv run roborock-local-server configure
 ```
 
-4. Generate an admin session secret.
+The wizard asks only for:
 
-```bash
-uv run roborock-local-server generate-secret
-```
+- your `stack_fqdn`
+- embedded MQTT or your own broker
+- whether to use Cloudflare DNS-01 auto-renew
+- your admin password
 
-Both commands print a single value to your terminal and do not save it to a file for you.
+It then writes `config.toml` for you, generates `admin.password_hash`, generates `admin.session_secret`, and if you chose Cloudflare it also writes `secrets/cloudflare_token`.
 
-- `hash-password` prints the value you should paste into `admin.password_hash`
-- `generate-secret` prints the value you should paste into `admin.session_secret`
-- if you did not save the output earlier, just run the command again and use the new value
-- if you change `session_secret` later, existing admin login sessions will be invalidated
+4. If you chose external MQTT, fill in `broker.host` in `config.toml` before starting the stack.
 
-5. Create the secrets folder and save your Cloudflare API token.
+5. If you skipped Cloudflare, put your certificate files in `data/certs/fullchain.pem` and `data/certs/privkey.pem`.
 
-```bash
-mkdir -p secrets
-printf '%s' 'YOUR_CLOUDFLARE_TOKEN' > secrets/cloudflare_token
-chmod 600 secrets/cloudflare_token
-```
+6. If you prefer doing setup manually, the wizard is equivalent to:
+
+- `uv run roborock-local-server hash-password`
+- `uv run roborock-local-server generate-secret`
+- creating `secrets/cloudflare_token` yourself
+- writing `config.toml` yourself
 
-6. Create `config.toml` with this baseline configuration.
+7. The wizard produces a config in this shape.
 
 ```toml
 [network]
@@ -206,17 +200,17 @@ session_secret = "PASTE_THE_SECRET_FROM_GENERATE_SECRET"
 session_ttl_seconds = 86400
 ```
 
-7. In your private DNS, point `roborock.example.com` to your server's LAN IP.
+8. In your private DNS, point `roborock.example.com` to your server's LAN IP.
 
-8. Start the stack.
+9. Start the stack.
 
 ```bash
 docker compose up --build -d
 ```
 
-9. Open `https://roborock.example.com/admin` from a device on the same LAN.
+10. Open `https://roborock.example.com/admin` from a device on the same LAN.
 
-10. Sign in and use the Cloud Import section to request an email code and import your Roborock cloud data.
+11. Sign in and use the Cloud Import section to request an email code and import your Roborock cloud data.
 
 ## External MQTT
 
@@ -288,6 +282,7 @@ The admin UI is intentionally small:
 - show service health
 - show known vacuums
 - import cloud data with email-code login
+- pair a device and track onboarding progress
 - show built-in support links for the project
 
 ## Persistent Data

compose.yaml

@@ -5,13 +5,9 @@ services:
       dockerfile: Dockerfile
     container_name: roborock-local-server
     restart: unless-stopped
-    cap_add:
-      - NET_ADMIN
     ports:
       - "443:443"
       - "8883:8883"
-      - "8081:8081"
-      - "51820:51820/udp"
     volumes:
       - ./config.toml:/app/config.toml:ro
       - ./data:/data

docs/custom_cert_management.md

@@ -0,0 +1 @@
+# TODO

docs/custom_mqtt.md

@@ -0,0 +1 @@
+# TODO

docs/index.md

@@ -0,0 +1 @@
+

docs/installation.md

@@ -0,0 +1,61 @@
+# Installation
+
+## Requirements:
+
+- Docker
+- Python
+- Two machines (one to run the server and one to do the onboarding)
+- A domain name that you own
+- A machine that can host this with the following ports exposed (INTERNALLY in YOUR network):
+```
+443
+8883
+```
+
+## Docker Setup
+
+1. You should clone this repository:
+
+`git clone https://github.com/Python-roborock/local_roborock_server`
+
+2. Change into the project folder.
+
+```bash
+cd roborock_local_server
+```
+
+3. Install the local project environment.
+
+```bash
+uv sync
+```
+
+4. Run the setup wizard.
+
+```bash
+uv run roborock-local-server configure
+```
+
+The wizard asks only for:
+
+- your `stack_fqdn` (this is your URL for your server. It MUST start with 'api-')
+- embedded MQTT or your own broker
+- whether to use Cloudflare DNS-01 auto-renew
+- your admin password
+
+It then writes `config.toml` for you, generates `admin.password_hash`, generates `admin.session_secret`, and if you chose Cloudflare it also writes `secrets/cloudflare_token`.
+
+5. If you chose external MQTT, fill in `broker.host` in `config.toml` before starting the stack. See: [Custom MQTT](#Custom_mqtt)
+
+6. If you skipped Cloudflare, put your certificate files in `data/certs/fullchain.pem` and `data/certs/privkey.pem`. See: [Custom cert](#custom_cert)
+
+7. Decide on your url. it must start with 'api-'. Set the DNS record on your network to resolve your url to your server.
+
+If your server is 'api-roborock.example.com', you should set the following DNS records to resolve to your server ip:
+'api-roborock.example.com'
+'mqtt-roborock.example.com'
+
+7. Now you can start the container by running:
+`docker-compose up -d --build`
+
+8.

mkdocs.yml

@@ -0,0 +1,7 @@
+site_name: Roborock Local Server
+
+theme:
+  name: material
+
+nav:
+  - Home: index.md