sms-handler/README.md

## Installation

Use `uv` (<https://docs.astral.sh/uv/getting-started/installation>).
Easy way to install `uv` on Debian:

```sh
apt install -y pipx && pipx install uv
```

## Configuration

Configuration is done by environment variables, prefixed by `SMS_HANDLER_`:

* `SMS_HANDLER_MAIL_SENDER`: origin email address (default: *username*@localhost)
* `SMS_HANDLER_MAIL_TO`: destination email address (default: *username*@localhost)
* `SMS_HANDLER_MAIL_SERVER`: address of the mail server (default: localhost)
* `SMS_HANDLER_MAIL_SERVER_PORT`: port of the mail server (default: 25)
* `SMS_HANDLER_MAIL_SERVER_START_TLS`: initiate mail server connection with TLS (default: no)
* `SMS_HANDLER_MAIL_TEMLATE`: used to format the body of the mails
* `SMS_HANDLER_MAIL_ENABLE`: no or false to disable mails (default: yes)

The default settings assume that a mail server runs on the localhost,
and mails are sent to the user that owns the process.

### SMS handler app configuration

Set the *Webhook URL* with as `https://your.server.name:8025/sms-handle`.
The URI path `/sms-handle` is not configurable.

## Run

### In foreground

```sh
sms-handler
```

Set port and listen address:

```sh
sms-handler --port 80125 --host 192.168.100.55
```

### As a deamon (Systemd)

Create a service as follows.
Pass the settings for the web server (listen address, port) in the ExecStart statement,
and the parameters as `Environment=MAIL_SERVER_START_TLS=yes`.

```systemd
[Unit]
Description=SMS handler

[Service]
ExecStart=/home/snoopy/.local/bin/sms-handler
Environment=SMS_HANDLER_MAIL_SENDER=snoopy@peanuts.com
Environment=SMS_HANDLER_MAIL_TO=snoopy@peanuts.com
Restart=on-failure

[Install]
WantedBy=default.target
```

### Container

Use `podman` or `docker`:

```sh
podman run tiptop:5000/sms_handler
```

**Note**: the container is not published publicly yet.

Pass parameters like this:

```sh
podman run -e SMS_HANDLER_MAIL_SERVER_PORT=8025 -e SMS_HANDLER_MAIL_SENDER=snoopy@peanuts.com SMS_HANDLER_MAIL_TO=snoopy@peanuts.com tiptop:5000/sms_handler
```

#### Container as a systemd service

Systemd can "orchestrate" containers easily thanks to podman.

##### Rootlass (as regular user)

For a rootless container, create a file in `.config/containers/systemd/sms-handler.container`:

```systemd
[Container]
ContainerName=sms-handler
Environment=SMS_HANDLER_MAIL_SENDER=snoopy@peanuts.com
Environment=SMS_HANDLER_MAIL_TO=snoopy@peanuts.com
Image=tiptop:5000/sms_handler
Network=podman
PublishPort=80°25:8025

[Service]
Restart=always

[Install]
WantedBy=default.target
```

Request systemd to reload configuration, creating the service for this container:

```sh
systemctl --user daemon-reload
```

Start the container as a service:

```sh
systemctl start sms-handler.service
```

To start rootless containers at boot time, without the need for the user (snoopy) to log in:

```sh
sudo loginctl enable-linger snoopy
```

##### Rootful (as root)

For a rootless container, create a file in `/etc/containers/systemd/sms-handler.container`:

```systemd
[Container]
ContainerName=sms-handler
Environment=SMS_HANDLER_MAIL_SENDER=snoopy@peanuts.com
Environment=SMS_HANDLER_MAIL_TO=snoopy@peanuts.com
Image=tiptop:5000/sms_handler
Network=podman
PublishPort=80°25:8025

[Service]
Restart=always

[Install]
WantedBy=default.target
```

Request systemd to reload configuration, creating the service for this container:

```sh
sudo systemctl daemon-reload
```

Start the container as a service:

```sh
sudo systemctl start sms-handler.service
```