# Home Assistant Ingress

MealPlanner can be exposed through Home Assistant by installing the `mealplanner-ingress` add-on. The add-on is an authenticated Ingress proxy to the existing MealPlanner Docker deployment; it does not run the database, backend, or frontend itself.

## Install

- In Home Assistant, go to Settings -> Add-ons -> Add-on Store -> Repositories.
- Add this repository URL: `https://git.research.bike/admin/Meal-Planner.git`.
- Install `MealPlanner Ingress` from the add-on store.
- Set `upstream_url` to the LAN URL for the existing MealPlanner nginx service, for example `http://192.168.1.54:8082`.
- Start the add-on and open the `MealPlanner` sidebar item.

## Required MealPlanner Env

Set these in MealPlanner's `.env` before exposing it through Home Assistant:

```env
ADMIN_TOKEN=<random-admin-token>
SESSION_PASSWORD=<family-shared-password>
SECRET_KEY=<random-secret>
SESSION_COOKIE_SECURE=false
TRUSTED_NETWORK_AUTO_AUTH=true
```

Home Assistant is the authentication boundary in this setup. `TRUSTED_NETWORK_AUTO_AUTH=true` removes the extra MealPlanner password prompt, so do not port-forward MealPlanner directly.

## Network Model

- Public Internet -> Home Assistant auth/MFA -> Ingress -> MealPlanner LAN URL.
- Do not port-forward MealPlanner directly.
- Keep the existing MealPlanner compose stack bound to the LAN only.

## Troubleshooting

- `could not read Username`: the Git repository is not anonymously cloneable from Home Assistant. Make the repository public, or use a separate public add-on repository.
- `not a valid app repository`: Home Assistant cloned the repository, but did not find valid add-on metadata. Confirm `repository.yaml` exists at the repository root and `mealplanner-ingress/config.yaml` exists on the default branch.
- Short/clipped display: do not use an embedded WebURL card for this app. Use the `MealPlanner Ingress` add-on sidebar item so Home Assistant proxies the full UI.