Files

user f4f3132b6b feat: systemd user service file for headless deployment

Hardened unit with ProtectSystem/ProtectHome, auto-restart on failure,
and ExecReload for SIGHUP hot config reload. Docs updated with setup,
management, and enable-linger instructions.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-21 19:25:36 +01:00

2.5 KiB

Raw Permalink Blame History

Installation

Prerequisites

Python 3.10+
SOCKS5 proxy running on 127.0.0.1:1080

Container Deployment (Recommended)

See DEPLOY.md for full podman/container instructions.

cp config/bouncer.example.toml config/bouncer.toml
$EDITOR config/bouncer.toml
make build && make up

Local Setup

cd ~/git/bouncer
make dev

This creates .venv/, installs all dependencies, and registers the bouncer command via editable install.

Verify

bouncer --version

Configuration

cp config/bouncer.example.toml config/bouncer.toml

Edit config/bouncer.toml. Required settings:

Key	Description
`bouncer.password`	Password for client authentication
`networks.<name>.host`	IRC server hostname
`networks.<name>.nick`	Your desired IRC nick

Optional but recommended:

Key	Default	Description
`networks.<name>.tls`	`false`	Enable TLS to IRC server
`networks.<name>.port`	`6667`/`6697`	Server port (auto-set by tls)
`networks.<name>.channels`	`[]`	Channels to auto-join
`networks.<name>.autojoin`	`true`	Join channels after probation

Symlink

To make bouncer available system-wide:

ln -sf ~/git/bouncer/.venv/bin/bouncer ~/.local/bin/bouncer

Verify:

which bouncer

Systemd (User Service)

Install and enable the bouncer as a user service (no root required):

mkdir -p ~/.config/systemd/user
cp config/bouncer.service ~/.config/systemd/user/bouncer.service

Edit ExecStart= paths if your install differs from the defaults:

$EDITOR ~/.config/systemd/user/bouncer.service

Enable and start:

systemctl --user daemon-reload
systemctl --user enable bouncer
systemctl --user start bouncer

Enable lingering so the service runs without an active login session:

sudo loginctl enable-linger $USER

Management

systemctl --user status bouncer       # check status
systemctl --user restart bouncer      # restart
systemctl --user stop bouncer         # stop
journalctl --user -u bouncer -f       # follow logs
systemctl --user reload bouncer       # hot reload config (SIGHUP)

Dependencies

Installed automatically by make dev:

Package	Purpose
`python-socks[asyncio]`	Async SOCKS5 proxy support
`aiosqlite`	Async SQLite for backlog
`ruff`	Linter (dev)
`black`	Formatter (dev)
`pytest`	Tests (dev)
`pytest-asyncio`	Async test support (dev)

2.5 KiB Raw Permalink Blame History