# hmdooris - Dooris via HomeMatic

## Configuration

All configuration is handled through environment variables.

| Name                            | Default                                                                 | Description                                                                              |
|---------------------------------|-------------------------------------------------------------------------|------------------------------------------------------------------------------------------|
| `HMDOORIS_ALLOWED_IPS`          | -                                                                       | List of IP addresses in CIDR notation that are allowed to control the locks.             |
| `HMDOORIS_DISCOVERY_URL`        | `http://localhost:8080/realms/testing/.well-known/openid-configuration` | OIDC configuration discovery URL.                                                        |
| `HMDOORIS_CCUJACK_URL`          | `https://raspberrymatic:2122`                                           | URL of the CCU Jack server.                                                              |
| `HMDOORIS_CCU_CERTIFICATE_PATH` | -                                                                       | File of a private certificate, or `false`.                                               |
| `HMDOORIS_CCUJACK_USERNAME`     | -                                                                       | Username in CCU Jack.                                                                    |
| `HMDOORIS_CCUJACK_PASSWORD`     | -                                                                       | Password in CCU Jack.                                                                    |
| `HMDOORIS_CLIENT_ID`            | `hmdooris`                                                              | OIDC client ID.                                                                          |
| `HMDOORIS_CLIENT_SECRET`        | -                                                                       | ODIC client secret for the confidential flow.                                            |
| `HMDOORIS_LISTEN`               | `127.0.0.1:3000`                                                        | Which IP and port to listen on.                                                          |
| `IDINVITE_OIDC_SCOPE`           | `["openid", "email", "profile"]`                                        | JSON list of OIDC scopes to request. The OIDC IDP will need to send the group attribute. |
| `IDINVITE_OIDC_USER_ATTR`       | `email`                                                                 | The attribute to use as the user ID.                                                     |
| `HMDOORIS_REQUIRES_GROUP`       | -                                                                       | Set to require users to be a member of this groups.                                      |
| `HMDOORIS_URL`                  | `http://localhost:3000`                                                 | URL of the application, used to construct links to itself.                               |

### Required Group

If you would like to restrict lock operations to members of a particular group, configure the OIDC client to add group
information to the ID token, and set `HMDOORIS_REQUIRES_GROUP` to the name of the group you would like to use.

Otherwise, all users that can authenticate successfully can operate the locks.

### TLS Certificate Configuration

If you'd like to secure access to CCU Jack via TLS, you either need to install a publically trusted certificate on
RaspberryMatic. If you are using a private certificate, you will need to use `HMDOORIS_CCU_CERTIFICATE_PATH` to point
the HTTP client to a suitable CA certificate. Setting the variable to `false` will disable certificate verification.
Alternatively, you can use plain `http`.

## Managing the CCU certificate

If you want to talk to the RaspberryMatic/CCU-Jack and you are using a self-signed certificate (which is the default),
you will need to supply that certificate to `hmdooris`.

1. Create a self-signed certificate:

```shell
openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 \
  -nodes -keyout hmdooris-ccu.ccchh.net.key -out hmdooris-ccu.ccchh.net.crt -subj "/CN=hmdooris-ccu.ccchh.net" \
  -addext "subjectAltName=DNS:hmdooris-ccu.ccchh.net"
cat hmdooris-ccu.ccchh.net.crt hmdooris-ccu.ccchh.net.key >hmdooris-ccu.ccchh.net.certkey.pem
```

2. Save the certificate to a file:

```shell
echo | \
  openssl s_client -servername hmdooris-ccu.ccchh.net -connect hmdooris-ccu.ccchh.net:2122 | \
  openssl x509 -text >self-signed.cert
```

2. Start `hmdooris` and pass the path to the file in the environment variable `HMDOORIS_CCU_CERTIFICATE_PATH`.

If you only want to use http, or your CCU has a public certificate (from for example Let's Encrypt), then you don't need
to do anything.

## Local Development Setup with Docker Compose

The included docker-compose.yaml will bring up a local Keycloak instance with a preconfigured realm that includes a
client that can be used to test the application locally. You can log in to the admin console
at http://localhost:8080/admin/master/console/ using "admin"/"admin".

### Realm `Keycloak`: Client `hmdooris` and User `hmdooris`

In order for ID Invite to create users, it needs to access the Keycloak REST API with suitable credentials. This is
implemented through a client `hmdooris` in the `Keycloak` realm, with the client secret `XXX`, and a username
of `hmdooris` and password `geheim`.

### Realm `testing`: Client `hmdooris` and User `tony`

Keycloak will import the realm export from [`local-dev/import/testing.json`](local-dev/import/testing.json) and create a
realm `testing`, including a client and a user.

The client ID is `hmdooris` and the secret is ´8p21riiYPDEhpgRh2rgRDNu9uWVZ9KRj`.

You can log in to the realm and the application with user `tony` and password `tester`.

### Updating the testing realm

If you'd like to make changes to the configuration of the testing realm, and have it persist across restarts, you can
export the realm. Run this command:

```shell
docker compose exec -it keycloak /opt/keycloak/data/import/export.sh
```