sms-handler/README.md

Listen to messages from the SMS Forwarder app on Android and send mail.

## 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_`:

* MAIL_SENDER: origin email address (default: <username>@localhost)
* MAIL_TO: destination email address (default: <username>@localhost)
* MAIL_SERVER: address of the mail server (default: localhost)
* MAIL_SERVER_PORT: port of the mail server (default: 25)
* MAIL_SERVER_START_TLS: initiate mail server connection with TLS (default: no)
* MAIL_TEMLATE: used to format the body of the mails
* 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
fastapi run server:app
```

Try `fastapi --help` for configuration of the server:
port, address to listen on, etc. For example:

```sh
fastapi run server:app --port 8025
```

### 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`.

    [Unit]
    Description=SMS handler
    
    [Service]
    ExecStart=fastapi run server:app
    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`:

podman run tiptop:5000/sms_handler

```

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`:

    [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`:

    [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
```