109 lines
3.2 KiB
Markdown
109 lines
3.2 KiB
Markdown
# About sms-handler
|
|
|
|
[sms-handler](https://philo.ydns.eu/code/Philome/sms-handler) is a simple companion service of the
|
|
*SMS ForwardX* app 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*
|
|
(available on [FDroid](https://f-droid.org/packages/com.pierreduchemin.smsforward/)),
|
|
use the [ntfy](https://ntfy.sh/) pub/sub service. It makes it easy
|
|
to integrate with other tools, for notification on various devices and automation.
|
|
|
|
## Installation
|
|
|
|
```sh
|
|
PIP_EXTRA_INDEX_URL=https://pypi.org/simple/ pip install --index-url https://philo.ydns.eu/code/api/packages/Philome/pypi/simple/ sms-handler
|
|
```
|
|
|
|
Debian and other systems require using `pipx` `pip`:
|
|
|
|
```sh
|
|
sudo apt install -y pipx
|
|
PIP_EXTRA_INDEX_URL=https://pypi.org/simple/ pipx install --index-url https://philo.ydns.eu/code/api/packages/Philome/pypi/simple/ sms-handler
|
|
```
|
|
|
|
## 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 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`.
|
|
|
|
*Note*: the URI path `/sms-handle` is not configurable.
|
|
|
|
## Run
|
|
|
|
### In foreground
|
|
|
|
```sh
|
|
sms-handler
|
|
```
|
|
|
|
Set port and listen address:
|
|
|
|
```sh
|
|
sms-handler --port 80125 --host 192.168.100.55
|
|
```
|
|
|
|
### 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=SMS_HANDLER_MAIL_SERVER_START_TLS=yes`.
|
|
|
|
```systemd
|
|
[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
|
|
```
|
|
|
|
## Run behind a reverse proxy
|
|
|
|
*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.
|
|
|
|
Example for [Caddy](https://caddyserver.com/):
|
|
|
|
```caddyfile
|
|
handle /sms-handler/* {
|
|
uri strip_prefix /sms-handler
|
|
reverse_proxy 192.168.100.2:8025
|
|
}
|
|
```
|
|
|
|
## Development and test
|
|
|
|
*sms-handler* is packaged with [uv](https://docs.astral.sh/uv/).
|
|
|
|
Download source code, create a Python virtual environment, install dependencies and run the tests:
|
|
|
|
```sh
|
|
git clone https://philo.ydns.eu/code/Philome/sms-handler.git
|
|
cd sms-handler
|
|
uv venv
|
|
uv sync
|
|
. .venv/bin/activate
|
|
pytest -s tests/basic.py
|
|
```
|