Installation

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

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

sms-handler

Set port and listen address:

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.

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

podman run tiptop:5000/sms_handler

Note: the container is not published publicly yet.

Pass parameters like this:

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:

systemctl --user daemon-reload

Start the container as a service:

systemctl start sms-handler.service

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

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:

sudo systemctl daemon-reload

Start the container as a service:

sudo systemctl start sms-handler.service