Initial commit

2024-12-01 00:53:31 +01:00 · 2024-12-01 00:53:31 +01:00 · 2463355b0b
commit 2463355b0b
11 changed files with 1029 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,147 @@
+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
+```