petrbalvin/nuntius
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

refactor: replace install.sh with Python install.py

Browse Source
This commit is contained in:
petrbalvin
2026-07-26 20:44:10 +02:00
parent 83c95dff08
commit 9a904fda8a
8 changed files with 270 additions and 160 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+1 -1
View File
@@ -44,7 +44,7 @@ secrets. Its only dependency outside the standard library is the first-party
`/etc/nuntius/config.toml` on first start.
- **systemd unit** — installed inline from `docs/deployment.md` with
`Restart=on-failure` and `EnvironmentFile=`.
- **Install script** — `install.sh`, idempotent, handles user creation, config
- **Install script** — `install.py`, idempotent, handles user creation, config
generation, and secrets file mode `0600`.
- **docs/** — `architecture.md`, `configuration.md`, `api-reference.md`,
`deployment.md`, `security.md`, `library-usage.md`.
CONTRIBUTING.md
+1 -1
View File
@@ -140,7 +140,7 @@ nuntius/
├── examples/
│ └── minimal/ # Standalone usage of pkg/contactform (no HTTP server)
├── docs/ # Architecture, configuration, API, deployment, security, library usage
├── install.sh # One-shot server installer (idempotent)
├── install.py # One-shot server installer (idempotent)
├── justfile # install, build, test, run, uninstall
├── go.mod # Go 1.26, no external dependencies
└── LICENSE # MIT
__pycache__/install.cpython-314.pyc
BIN
View File
Binary file not shown.
docs/configuration.md
+1 -1
View File
@@ -160,7 +160,7 @@ NUNTIUS_SMTP_PASSWORD=actual-app-password
EnvironmentFile=/etc/nuntius/.env
```
The `install.sh` helper script sets the file mode automatically.
The `install.py` helper script sets the file mode automatically.
## Defaults at a Glance
docs/deployment.md
+3 -3
View File
@@ -37,7 +37,7 @@ rsync -avz \
user@your-server:/tmp/nuntius/
```
> `install.sh` lives in the repository root. The systemd unit is included inline in Option A below (you do not need to rsync it from the repo). `.env.example` is a template for the secrets file. Adjust the `rsync` source list to match what you keep checked in.
> `install.py` lives in the repository root. The systemd unit is included inline in Option A below (you do not need to rsync it from the repo). `.env.example` is a template for the secrets file. Adjust the `rsync` source list to match what you keep checked in.
## 2. Install on the Server (SSH Session)
@@ -97,7 +97,7 @@ sudo journalctl -u nuntius -f
The service file expects the binary at `/usr/local/bin/nuntius`, the env file at `/etc/nuntius/.env`, and the data dir at `/var/lib/nuntius` (the config's `data_dir: "./data"` resolves to `/var/lib/nuntius/data` because the unit sets `WorkingDirectory=/var/lib/nuntius`). If you'd rather use `/opt/nuntius/...` or any other layout, edit the systemd unit block above before installing.
### Option B — `install.sh` (idempotent)
### Option B — `install.py` (idempotent)
Before running the script, copy the systemd unit from the block in Option A above into `/tmp/nuntius/nuntius.service` (the script reads it from the current working directory):
@@ -106,7 +106,7 @@ ssh user@your-server
cd /tmp/nuntius
# Paste the [Unit]…[Install] block from Option A into this file:
sudo $EDITOR /tmp/nuntius/nuntius.service
sudo bash install.sh
sudo python3 install.py
```
The script is idempotent: re-running on an already-installed host is safe. It:
docs/security.md
+1 -1
View File
@@ -100,7 +100,7 @@ Things nuntius does **not** do:
Things you should do:
- Make sure `/etc/nuntius/.env` is `0600` and owned `root:nuntius` (the `install.sh` script does this for you).
- Make sure `/etc/nuntius/.env` is `0600` and owned `root:nuntius` (the `install.py` script does this for you).
- Use an app-specific password or OAuth token if your provider supports it. nuntius uses `PLAIN` auth because that is what every SMTP provider offers; the credential is the secret, not the auth mechanism.
- Rotate the password on the same cadence as any other production secret.
- Restrict read access to `journalctl -u nuntius` if you do not want the client IPs in your local log files.
install.py
+263
View File
@@ -0,0 +1,263 @@
#!/usr/bin/env python3
#
# install.py — install nuntius as a systemd service.
#
# nuntius ships as a single static binary. Build it on your workstation, upload
# the binary, the systemd unit, and the .env template to the server, then run
# this script there as root from that directory:
#
# scp bin/nuntius nuntius.service .env.example user@host:/tmp/nuntius/
# ssh user@host
# cd /tmp/nuntius && sudo python3 install.py
#
# It expects ./nuntius and ./nuntius.service (and optionally ./.env.example) in
# the current working directory. Idempotent: re-running is safe — it skips the
# user, config, and .env when they already exist, and never starts the service.
from __future__ import annotations
import argparse
import logging
import os
import shutil
import subprocess
import sys
from typing import NoReturn
NUNTIUS_USER = "nuntius"
BIN_DEST = "/usr/local/bin/nuntius"
CONFIG_DIR = "/etc/nuntius"
CONFIG_FILE = "/etc/nuntius/config.toml"
ENV_FILE = "/etc/nuntius/.env"
DATA_DIR = "/var/lib/nuntius"
SERVICE_DEST = "/etc/systemd/system/nuntius.service"
# ---------------------------------------------------------------------------
# Coloured logging
# ---------------------------------------------------------------------------
class _ColourFormatter(logging.Formatter):
"""Prefix each log line with a coloured level marker, mimicking the bash script."""
_COLOURS: dict[int, str] = {
logging.INFO: "\033[1;34m", # blue
logging.WARNING: "\033[1;33m", # yellow
logging.ERROR: "\033[1;31m", # red
}
_LABELS: dict[int, str] = {
logging.INFO: "==>",
logging.WARNING: "WARN:",
logging.ERROR: "ERROR:",
}
_RESET = "\033[0m"
def format(self, record: logging.LogRecord) -> str:
colour = self._COLOURS.get(record.levelno, "")
label = self._LABELS.get(record.levelno, "")
if colour and label:
return f"{colour}{label}{self._RESET} {record.getMessage()}"
return record.getMessage()
def _setup_logging() -> None:
"""Configure the root logger with coloured console output."""
logger = logging.getLogger()
logger.setLevel(logging.INFO)
handler = logging.StreamHandler()
handler.setFormatter(_ColourFormatter())
# Remove any handlers added by basicConfig or other imports.
logger.handlers.clear()
logger.addHandler(handler)
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
def _run(cmd: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
"""Run a command via subprocess and check for failure (unless told otherwise)."""
return subprocess.run(cmd, check=True, text=True, **kwargs)
# ---------------------------------------------------------------------------
# Install steps
# ---------------------------------------------------------------------------
def require_root() -> None:
"""Exit if not running as root."""
if os.geteuid() != 0:
logging.error("Run as root: sudo python3 install.py")
sys.exit(1)
def require_files() -> None:
"""Verify that the binary and the systemd unit are present in CWD."""
if not os.path.isfile("./nuntius"):
logging.error(
"./nuntius binary not found — copy it here first (e.g. rsync bin/nuntius)."
)
sys.exit(1)
if not os.path.isfile("./nuntius.service"):
logging.error(
"./nuntius.service not found — paste the unit from docs/deployment.md (Option A)."
)
sys.exit(1)
def create_user() -> None:
"""Create the system user if it does not already exist."""
try:
_run(["id", NUNTIUS_USER], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
logging.info("User %s already exists.", NUNTIUS_USER)
except subprocess.CalledProcessError:
logging.info("Creating system user %s…", NUNTIUS_USER)
_run(
[
"useradd",
"--system",
"--shell",
"/usr/sbin/nologin",
"--home-dir",
DATA_DIR,
"--user-group",
NUNTIUS_USER,
]
)
def create_data_dir() -> None:
"""Ensure the data directory exists with correct ownership and permissions."""
logging.info("Setting up %s…", DATA_DIR)
os.makedirs(DATA_DIR, exist_ok=True)
shutil.chown(DATA_DIR, user=NUNTIUS_USER, group=NUNTIUS_USER)
os.chmod(DATA_DIR, 0o750)
def install_binary() -> None:
"""Copy the nuntius binary to /usr/local/bin with mode 0755."""
logging.info("Installing binary to %s…", BIN_DEST)
shutil.copy2("./nuntius", BIN_DEST)
os.chmod(BIN_DEST, 0o755)
def install_service() -> None:
"""Copy the systemd unit file with mode 0644."""
logging.info("Installing systemd unit %s…", SERVICE_DEST)
shutil.copy2("./nuntius.service", SERVICE_DEST)
os.chmod(SERVICE_DEST, 0o644)
def generate_config() -> None:
"""Auto-generate the TOML config by running nuntius briefly if config is absent."""
if os.path.isfile(CONFIG_FILE):
logging.info("Config %s already exists; leaving it untouched.", CONFIG_FILE)
return
logging.info("Generating %s…", CONFIG_FILE)
os.makedirs(CONFIG_DIR, exist_ok=True)
# nuntius writes the template config on first start; run it briefly, then
# let `timeout` send SIGTERM (graceful shutdown). The write happens at
# startup, before the timeout elapses.
try:
_run(["timeout", "-k", "5s", "4s", BIN_DEST], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
except subprocess.CalledProcessError:
# timeout exits 124 on SIGTERM, 137 on SIGKILL — both are expected.
pass
if not os.path.isfile(CONFIG_FILE):
logging.warning("nuntius did not create %s; check the uploaded binary.", CONFIG_FILE)
# Fix ownership in case nuntius wrote files as root.
_run(["chown", "-R", f"{NUNTIUS_USER}:{NUNTIUS_USER}", DATA_DIR])
def install_env() -> None:
"""Copy .env.example to /etc/nuntius/.env if it does not already exist."""
if os.path.isfile(ENV_FILE):
logging.info("%s already exists; leaving it untouched.", ENV_FILE)
elif os.path.isfile("./.env.example"):
logging.info("Creating %s from .env.example (edit it!)…", ENV_FILE)
shutil.copy2("./.env.example", ENV_FILE)
os.chmod(ENV_FILE, 0o600)
_run(["chown", f"root:{NUNTIUS_USER}", ENV_FILE])
else:
logging.warning(
".env.example not found; skipping %s. Create it before starting.", ENV_FILE
)
def enable_service() -> None:
"""Reload systemd and enable the nuntius service (does not start it)."""
logging.info("Reloading systemd and enabling nuntius…")
_run(["systemctl", "daemon-reload"])
_run(["systemctl", "enable", "nuntius.service"])
def final_notes() -> None:
"""Print post-install instructions."""
print(
f"""
============================================================
✓ nuntius installed and enabled, but NOT started.
Next manual steps:
1. Set the SMTP password:
sudo $EDITOR {ENV_FILE}
2. Edit the auto-generated config (smtp.host, smtp.user, allowed_origins):
sudo $EDITOR {CONFIG_FILE}
3. Start the service:
sudo systemctl start nuntius
sudo journalctl -u nuntius -f
4. Add the nginx location block (see README.md), then:
sudo nginx -t && sudo systemctl reload nginx
============================================================
"""
)
# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------
def _build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(
prog="install.py",
description="install nuntius as a systemd service.",
epilog=(
"Idempotent: re-running is safe. The service is enabled but never started."
),
)
return parser
# ---------------------------------------------------------------------------
# Main
# ---------------------------------------------------------------------------
def main(argv: list[str] | None = None) -> NoReturn:
"""Parse args and run all install steps in order."""
_setup_logging()
parser = _build_parser()
parser.parse_args(argv)
require_root()
require_files()
create_user()
create_data_dir()
install_binary()
install_service()
generate_config()
install_env()
enable_service()
final_notes()
sys.exit(0)
if __name__ == "__main__":
main()
install.sh
-153
View File
@@ -1,153 +0,0 @@
#!/usr/bin/env bash
#
# install.sh — install nuntius as a systemd service.
#
# nuntius ships as a single static binary. Build it on your workstation, upload
# the binary, the systemd unit, and the .env template to the server, then run
# this script there as root from that directory:
#
# scp bin/nuntius nuntius.service .env.example user@host:/tmp/nuntius/
# ssh user@host
# cd /tmp/nuntius && sudo bash install.sh
#
# It expects ./nuntius and ./nuntius.service (and optionally ./.env.example) in
# the current working directory. Idempotent: re-running is safe — it skips the
# user, config, and .env when they already exist, and never starts the service.
set -euo pipefail
NUNTIUS_USER="nuntius"
BIN_DEST="/usr/local/bin/nuntius"
CONFIG_DIR="/etc/nuntius"
CONFIG_FILE="${CONFIG_DIR}/config.toml"
ENV_FILE="${CONFIG_DIR}/.env"
DATA_DIR="/var/lib/nuntius"
SERVICE_DEST="/etc/systemd/system/nuntius.service"
log() { printf '\033[1;34m==>\033[0m %s\n' "$*"; }
warn() { printf '\033[1;33mWARN:\033[0m %s\n' "$*" >&2; }
die() { printf '\033[1;31mERROR:\033[0m %s\n' "$*" >&2; exit 1; }
usage() {
cat <<'EOF'
install.sh — install nuntius as a systemd service.
Upload the binary, the systemd unit, and the .env template to the server, then
run this script there as root from that directory:
scp bin/nuntius nuntius.service .env.example user@host:/tmp/nuntius/
ssh user@host
cd /tmp/nuntius && sudo bash install.sh
Idempotent: re-running is safe. The service is enabled but never started.
EOF
exit 0
}
require_root() {
[ "$(id -u)" -eq 0 ] || die "Run as root: sudo bash install.sh"
}
require_files() {
[ -f ./nuntius ] || die "./nuntius binary not found — copy it here first (e.g. rsync bin/nuntius)."
[ -f ./nuntius.service ] || \
die "./nuntius.service not found — paste the unit from docs/deployment.md (Option A)."
}
create_user() {
if id "$NUNTIUS_USER" >/dev/null 2>&1; then
log "User ${NUNTIUS_USER} already exists."
else
log "Creating system user ${NUNTIUS_USER}…"
useradd --system --shell /usr/sbin/nologin --home-dir "$DATA_DIR" --user-group "$NUNTIUS_USER"
fi
}
create_data_dir() {
log "Setting up ${DATA_DIR}…"
mkdir -p "$DATA_DIR"
chown "$NUNTIUS_USER:$NUNTIUS_USER" "$DATA_DIR"
chmod 750 "$DATA_DIR"
}
install_binary() {
log "Installing binary to ${BIN_DEST}…"
install -m 0755 ./nuntius "$BIN_DEST"
}
install_service() {
log "Installing systemd unit ${SERVICE_DEST}…"
install -m 0644 ./nuntius.service "$SERVICE_DEST"
}
generate_config() {
if [ -f "$CONFIG_FILE" ]; then
log "Config ${CONFIG_FILE} already exists; leaving it untouched."
return
fi
log "Generating ${CONFIG_FILE}…"
mkdir -p "$CONFIG_DIR"
# nuntius writes the template config on first start; run it briefly, then
# let `timeout` send SIGTERM (graceful shutdown). No backgrounding or manual
# kill — the write happens at startup, before the timeout elapses.
timeout -k 5s 4s "$BIN_DEST" >/dev/null 2>&1 || true
[ -f "$CONFIG_FILE" ] || warn "nuntius did not create ${CONFIG_FILE}; check the uploaded binary."
chown -R "$NUNTIUS_USER:$NUNTIUS_USER" "$DATA_DIR"
}
install_env() {
if [ -f "$ENV_FILE" ]; then
log "${ENV_FILE} already exists; leaving it untouched."
elif [ -f ./.env.example ]; then
log "Creating ${ENV_FILE} from .env.example (edit it!)…"
install -m 0600 ./.env.example "$ENV_FILE"
chown "root:$NUNTIUS_USER" "$ENV_FILE"
else
warn ".env.example not found; skipping ${ENV_FILE}. Create it before starting."
fi
}
enable_service() {
log "Reloading systemd and enabling nuntius…"
systemctl daemon-reload
systemctl enable nuntius.service
}
final_notes() {
cat <<'EOF'
============================================================
✓ nuntius installed and enabled, but NOT started.
Next manual steps:
1. Set the SMTP password:
sudo $EDITOR /etc/nuntius/.env
2. Edit the auto-generated config (smtp.host, smtp.user, allowed_origins):
sudo $EDITOR /etc/nuntius/config.toml
3. Start the service:
sudo systemctl start nuntius
sudo journalctl -u nuntius -f
4. Add the nginx location block (see README.md), then:
sudo nginx -t && sudo systemctl reload nginx
============================================================
EOF
}
main() {
case "${1:-}" in
-h | --help) usage ;;
esac
require_root
require_files
create_user
create_data_dir
install_binary
install_service
generate_config
install_env
enable_service
final_notes
}
main "$@"