# Installation and operation

1. Go to **Settings → Apps → Install app → ⋮ → Repositories** and add this
   exact URL:
   `https://git.radixadm.dk/dennis/homeassistant-stelloauth-addon.git`.

2. Install **Stelloauth**, enable **Start on boot** and **Watchdog**, then start
   the app. Home Assistant builds a local image from source for the selected
   `amd64` or `aarch64` architecture. This repository does not publish a
   prebuilt image.

3. Wait for the app log to show these five readiness messages in order:

   ```text
   Cleaning CloakBrowser profiles
   Starting CloakBrowser
   CloakBrowser ready
   Starting Stelloauth
   Stelloauth listening on 0.0.0.0:8080
   ```

4. Keep the host port disabled during normal operation. For brief
   troubleshooting, map `8080/tcp` to host port `8080`. Then check
   `http://192.168.1.20:8080/` or the worker endpoint at
   `http://192.168.1.20:8080/worker`. **Disable the port mapping again** when
   you finish. The worker endpoint receives MyOpel details and has no separate
   authentication.

5. Open the **Stellantis Vehicles** integration's configuration and set
   **Login service URL** to exactly
   `http://0031621f-stelloauth:8080/worker`. The integration does not append
   `/worker`, so include the full path.

6. Select **Brand: Opel** and **Country: DK**, then complete the integration's
   OAuth setup with your MyOpel details.

7. The app provides three options:

   - `queue_timeout`: how long a login attempt may wait for the single session.
   - `rate_limit_count`: the maximum number of login attempts allowed in each
     period.
   - `rate_limit_duration`: the length of the login rate-limit period.

   `CLOAK_MAX_SESSIONS` is fixed at one because CloakBrowser's free tier allows
   one concurrent login. Additional attempts wait in the queue.

8. Each OAuth attempt gets a temporary profile under `/tmp/cloakserve`.
   CloakBrowser removes inactive browser processes after 30 seconds, and the
   process manager removes old profiles at startup. Credentials, cookies,
   tokens, and OAuth codes are not stored in `/data`. CDP listens only on the
   loopback address `127.0.0.1:9222`. Logs use fixed, redacted messages and do
   not include email addresses, passwords, URLs, codes, or tokens.

9. Measurements from a real `linux/amd64` run under Rosetta:

   - Image: 2,571,693,650 bytes (2.571 GB decimal / 2,452.56 MiB).
   - Documented Task 4 measurement: 121.5 MiB.
   - Stop time: about 9.3 seconds.
   - The `amd64` runtime passed under Rosetta; the `aarch64` build passed.

   A successful live MyOpel login has not been verified. Login-flow memory
   usage was not measured without real MyOpel credentials.

10. Troubleshooting and removal:

    - If a readiness message is missing, check for a timeout. CloakBrowser has
      60 seconds and Stelloauth has 30 seconds. Fix the cause, then restart the
      app.
    - An invalid or disallowed authorize URL returns HTTP `400`.
    - Too many login attempts return HTTP `429`; wait for the configured
      rate-limit period.
    - If the repository URL or hostname changes, the Supervisor repository ID
      and `0031621f-stelloauth` hostname also change. Calculate and use the new
      internal URL.
    - If disk space is low, check available space and remove unneeded images or
      backups through Supervisor before building again.
    - If the internal URL cannot be reached, use the temporary port check from
      step 4, then disable the port mapping again.
    - To remove the app, go to **Settings → Apps → Stelloauth → Uninstall**.
      Supervisor stops the container and removes the app's local data. If you
      no longer need the repository, remove it from **Settings → Apps → Install
      app → ⋮ → Repositories** as well.

## Sources and licenses

App version `0.1.0` builds Stelloauth `v0.6.0` from commit
`367d4f8c02a3b072c59142c49dffc129edc8548b` and uses the official CloakBrowser
`0.5.10` image at OCI index digest
`sha256:2ed5b2d047cbdde22cde7ef1a796526c716aadaa5bccbe1db5ade49282b64a76`.
The repository's original files and patches are licensed under the MIT License.
The proprietary CloakBrowser binary remains subject to the separate
**CloakBrowser Binary License**. It is not licensed under MIT or redistributed
by this repository.