diff --git a/README.md b/README.md index 2f0ef8d..9ac34ad 100644 --- a/README.md +++ b/README.md @@ -108,19 +108,27 @@ Run the bot: python main.py ``` -## Simple Linux launch with screen +## Deployment on Ubuntu 24.04 -Install system packages: +### Simple screen run + +This option runs the bot manually inside a GNU `screen` session under a regular +Linux user. It is useful for development and debugging because you can reconnect +to the bot session, but it does not start the bot automatically after a server +reboot. + +Install the required system packages: ```bash sudo apt update sudo apt install -y git python3 python3-venv python3-pip screen ``` -Clone the project and prepare the environment: +Clone and configure the project in the regular user's home directory: ```bash -git clone +cd ~ +git clone https://github.com/deKibi/cryptocodi-bot.git cd cryptocodi-bot python3 -m venv .venv source .venv/bin/activate @@ -129,23 +137,161 @@ cp .env.example .env nano .env ``` -Create a `screen` session and start the bot: +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/cryptocodi-bot +``` + +### If systemd autostart is configured + +This block is only relevant if you configured and started the `cryptocodi-bot` +systemd service. Do not run the bot in `screen` while the systemd service is +already running, because that starts two bot instances at the same time. + +Check whether the service is running: + +```bash +sudo systemctl status cryptocodi-bot +``` + +Stop the service before starting the bot manually in `screen`: + +```bash +sudo systemctl stop cryptocodi-bot +sudo journalctl -u cryptocodi-bot -n 50 +``` + +Start a named `screen` session: ```bash screen -S cryptocodi-bot +``` + +Inside the `screen` session, start the bot: + +```bash source .venv/bin/activate python main.py ``` -To leave the bot running in the background, press `Ctrl+A`, then `D`. +Useful `screen` controls: + +- Detach while keeping the bot running: press `Ctrl+A`, then `D`. +- Reconnect to the bot session: `screen -r cryptocodi-bot`. +- List sessions: `screen -ls`. +- Stop the bot after reconnecting: press `Ctrl+C`. + +Run the bot again later without repeating the clone and setup steps: + +```bash +cd ~/cryptocodi-bot +screen -S cryptocodi-bot +source .venv/bin/activate +python main.py +``` -Return to the session: +After stopping the bot in `screen`, start the systemd service again if needed: + +```bash +sudo systemctl start cryptocodi-bot +sudo systemctl status cryptocodi-bot +sudo journalctl -u cryptocodi-bot -f +``` + +### Run as a systemd service + +Use this option when the bot should start together with the system and restart +after crashes. + +Create the service file: + +```bash +sudo nano /etc/systemd/system/cryptocodi-bot.service +``` + +Replace `User=denys` and `/home/denys/cryptocodi-bot` with your Linux user and +project path if needed. + +```ini +[Unit] +Description=Cryptocodi Telegram Bot +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple +User=denys +WorkingDirectory=/home/denys/cryptocodi-bot +Environment=PYTHONUNBUFFERED=1 +ExecStart=/home/denys/cryptocodi-bot/.venv/bin/python /home/denys/cryptocodi-bot/main.py +Restart=on-failure +RestartSec=10 + +[Install] +WantedBy=multi-user.target +``` + +Enable and start the service: + +Before starting the service, make sure the bot is not already running in +`screen`. If it is running, reconnect and stop it with `Ctrl+C`: ```bash screen -r cryptocodi-bot ``` -Stop the bot with `Ctrl+C` inside the screen session. +Check active `screen` sessions if needed: + +```bash +screen -ls +``` + +```bash +sudo systemctl daemon-reload +sudo systemctl enable cryptocodi-bot +sudo systemctl start cryptocodi-bot +``` + +Check service status: + +```bash +sudo systemctl status cryptocodi-bot +``` + +Useful service commands: + +```bash +sudo systemctl stop cryptocodi-bot +sudo systemctl status cryptocodi-bot +sudo systemctl start cryptocodi-bot +sudo systemctl restart cryptocodi-bot +sudo journalctl -u cryptocodi-bot -f +``` + +Useful `journalctl` controls: + +- Follow live systemd logs for the bot service: + `sudo journalctl -u cryptocodi-bot -f`. +- Stop following logs and return to the shell: press `Ctrl+C`. +- Pressing `Ctrl+C` here does not stop the bot; use + `sudo systemctl stop cryptocodi-bot` for that. + +## Logs + +Logs are written to: + +```text +logs/bot.log +logs/detected_time_convertions.jsonl +logs/detected_crypto_convertions.jsonl +logs/detected_calculations.jsonl +``` + +They rotate daily and keep the last 30 days. ## Structure