diff --git a/README.md b/README.md index f0af178..7406ee4 100644 --- a/README.md +++ b/README.md @@ -128,10 +128,13 @@ Logs are written to both the console and `logs/bot.log`. File logs rotate daily, and the latest 30 rotated files are retained. Original Telegram message text and bot tokens are not logged. -## Simple Deployment on Ubuntu 24.04 +## Deployment on Ubuntu 24.04 -This demo deployment runs the bot inside a GNU `screen` session. It does not set -up automatic restarts or other production infrastructure. +### Simple screen run + +This option runs the bot manually inside a GNU `screen` session under a regular +Linux user. It is simple and lets you reconnect to the bot session, but it does +not start the bot automatically after a server reboot. Install the required system packages: @@ -140,9 +143,10 @@ sudo apt update sudo apt install -y git python3 python3-venv screen ``` -Clone and configure the project: +Clone and configure the project in the regular user's home directory: ```bash +cd ~ git clone https://github.com/deKibi/codex-time-bot.git cd codex-time-bot python3 -m venv .venv @@ -153,13 +157,22 @@ cp .env.example .env nano .env ``` +Check the project path. This is only an example path to the cloned GitHub +repository; replace it with the actual path on your server where needed: + +```bash +pwd +# Example output: +# /home/denys/codex-time-bot +``` + Start a named `screen` session: ```bash screen -S codex-time-bot ``` -Inside the session, activate the environment and start the bot: +Inside the `screen` session, start the bot: ```bash source .venv/bin/activate @@ -169,5 +182,80 @@ python main.py Useful `screen` controls: - Detach while keeping the bot running: press `Ctrl+A`, then `D`. -- Reconnect: `screen -r codex-time-bot`. +- Reconnect to the bot session: `screen -r codex-time-bot`. +- List sessions: `screen -ls`. - Stop the bot after reconnecting: press `Ctrl+C`. + +### Run as a systemd service + +Use this option when the bot should start together with the system and restart +after crashes. This example still starts the bot inside `screen`, so you can +reconnect to the running session. + +First complete the setup from the simple `screen` run section above. Then create +a `systemd` service file: + +```bash +sudo nano /etc/systemd/system/codex-time-bot.service +``` + +Example service configuration: + +```ini +[Unit] +Description=Codex Time Bot +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple +User=denys +WorkingDirectory=/home/denys/codex-time-bot +Environment=PYTHONUNBUFFERED=1 +ExecStart=/usr/bin/screen -DmS codex-time-bot /home/denys/codex-time-bot/.venv/bin/python main.py +ExecStop=/usr/bin/screen -S codex-time-bot -X quit +Restart=on-failure +RestartSec=5 + +[Install] +WantedBy=multi-user.target +``` + +In this example, `denys` is the regular Linux user that runs the bot, and +`/home/denys/codex-time-bot` is only an example project path. Replace `User`, +`WorkingDirectory`, and the path in `ExecStart` with your actual values. + +Enable and start the service: + +```bash +sudo systemctl daemon-reload +sudo systemctl enable codex-time-bot +sudo systemctl start codex-time-bot +``` + +Check service status: + +```bash +sudo systemctl status codex-time-bot +``` + +Useful service commands: + +```bash +sudo systemctl stop codex-time-bot +sudo systemctl restart codex-time-bot +sudo journalctl -u codex-time-bot -f +``` + +To reconnect to the service-owned `screen` session: + +```bash +screen -r codex-time-bot +``` + +Detach with `Ctrl+A`, then `D`. Stop the service through `systemd` instead of +pressing `Ctrl+C` inside the session: + +```bash +sudo systemctl stop codex-time-bot +```