Update README

This commit is contained in:
phil 2024-12-01 13:12:34 +01:00
parent 0ac32cb47c
commit 6a581eae0a
2 changed files with 119 additions and 90 deletions

90
CONTAINER.md Normal file
View file

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

119
README.md
View file

@ -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 ## Installation
```sh ```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_TEMLATE`: used to format the body of the mails
* `SMS_HANDLER_MAIL_ENABLE`: no or false to disable mails (default: yes) * `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. and mails are sent to the user that owns the process.
### SMS handler app configuration ### SMS handler app configuration
Set the *Webhook URL* with as `https://your.server.name:8025/sms-handle`. 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 ## Run
@ -45,11 +59,11 @@ Set port and listen address:
sms-handler --port 80125 --host 192.168.100.55 sms-handler --port 80125 --host 192.168.100.55
``` ```
### As a deamon (Systemd) ### As a daemon (Systemd)
Create a service as follows. Create a service as follows.
Pass the settings for the web server (listen address, port) in the ExecStart statement, 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 ```systemd
[Unit] [Unit]
@ -65,92 +79,17 @@ Restart=on-failure
WantedBy=default.target 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 Example for [Caddy](https://caddyserver.com/):
podman run tiptop:5000/sms_handler
``` ```caddyfile
handle /sms-handler/* {
**Note**: the container is not published publicly yet! uri strip_prefix /sms-handler
reverse_proxy 192.168.100.2:8025
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
``` ```