From 6a581eae0a07e095cc81b9e4b13063cc3edd3a84 Mon Sep 17 00:00:00 2001 From: phil Date: Sun, 1 Dec 2024 13:12:34 +0100 Subject: [PATCH] Update README --- CONTAINER.md | 90 ++++++++++++++++++++++++++++++++++++++ README.md | 119 +++++++++++++-------------------------------------- 2 files changed, 119 insertions(+), 90 deletions(-) create mode 100644 CONTAINER.md diff --git a/CONTAINER.md b/CONTAINER.md new file mode 100644 index 0000000..546c8d3 --- /dev/null +++ b/CONTAINER.md @@ -0,0 +1,90 @@ +# 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. + +### Rootless (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=8025: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=8025: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 +``` + diff --git a/README.md b/README.md index cac3f40..2e3905d 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,16 @@ +# About sms-handler + +[sms-handler](https://philo.ydns.eu) is a simple companion service of the +[SMS Forward](https://gitlab.com/pierreduchemin/smsforward) app +(available on [FDroid](https://f-droid.org/packages/com.pierreduchemin.smsforward/)) +designed to send notification mails on reception of SMSes. + +It is written in Python with [FastAPI](https://fastapi.tiangolo.com/) and BSD licensed. + +For a more flexible way to use *SMS Forward*, it can be used with +the [ntfy](https://ntfy.sh/) pub/sub service, making it easy +to integrate with other tools, for notification on various devices and automation. + ## Installation ```sh @@ -23,13 +36,14 @@ Configuration is done by environment variables, prefixed by `SMS_HANDLER_`: * `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, +The default settings work with 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. + +*Note*: the URI path `/sms-handle` is not configurable. ## Run @@ -45,11 +59,11 @@ Set port and listen address: sms-handler --port 80125 --host 192.168.100.55 ``` -### As a deamon (Systemd) +### As a daemon (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`. +and the parameters as `Environment=SMS_HANDLER_MAIL_SERVER_START_TLS=yes`. ```systemd [Unit] @@ -65,92 +79,17 @@ Restart=on-failure WantedBy=default.target ``` -### Container +## Run behind a reverse proxy -Use `podman` or `docker`: +*sms-handler* can run behind a reverse proxy (Nginx, Apache, etc) +for HTTPs support. The URI (configured in the *SMS Forward* app) can be prefixed +to dispatch different applications on the same server. -```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=8025: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=8025: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 +Example for [Caddy](https://caddyserver.com/): + +```caddyfile +handle /sms-handler/* { + uri strip_prefix /sms-handler + reverse_proxy 192.168.100.2:8025 +} ```