🪓 Tupac Almighty 🔫 Docker & RPI Deployment Guide

About This Project

Tupac Almighty is a personal Telegram bot that runs 24/7 on a Raspberry Pi and uses a local Mac for heavy-duty tasks.

It uses a "mac-as-a-server" setup: the RPi handles simple commands, but for demanding tasks like AI chats or transcribing voice notes, it connects to the Mac to borrow its power. This makes the bot both efficient and powerful, without any cloud costs.

Key Features:

• 🤖 Ask AI: Chat with various local Large Language Models (LLMs).
• 🎙️ Voice-to-Text: Transcribe audio messages using Whisper.
• 🎯 Appointment Sniper: Automatically checks a website for open shooting range appointments.
• 🗓️ Activity Tracker: Fetches events from Google Calendar to track personal goals.

---

This guide covers local development, Docker usage, and Raspberry Pi deployment—including systemd integration for robust service management.

---

🛡️ Environment Setup

1. Copy .env.example to .env and fill in all required values:

   cp .env.example .env

---

📦 Local Development

Recommended: Use pyenv & pyenv-virtualenv for Python isolation.

1. (Optional but recommended) Set up a virtual environment:

   pyenv install 3.13.2
   pyenv virtualenv 3.13.2 "$PROJECT_NAME"
   pyenv local "$PROJECT_NAME"

2. Install dependencies:

   pip install -r requirements.txt

3. Run the application:

   python main.py

You can skip the virtualenv steps and use your system Python if you prefer, but isolation is safer for dependencies.

---

🐳 Running with Docker

1. Build the Docker image (ARM64 for RPi):

   docker build --platform linux/arm64 -t tupac .

2. Run the container:

   docker run --rm -it tupac

3. Detached mode:

   docker run -d --name tupac tupac

---

🔄 Deploying to Raspberry Pi

1️⃣ Automated Deployment

Use the deployment script for a full build-transfer-deploy cycle:

chmod +x scripts/deploy.sh
./scripts/deploy.sh

• Builds the image locally for ARM64
• Saves as a tarball
• Transfers image, .env, docker-compose.yml, and config/ to the Pi
• Loads and runs via Docker Compose on the Pi

Paths:

• Script: scripts/deploy.sh
• Service file: config/telegram-bot.service.ini

2️⃣ Manual Deployment (Advanced)

docker save -o tupac.tar tupac
scp tupac.tar pi@<PI_HOST>:/home/pi/
ssh pi@<PI_HOST> "docker load -i /home/pi/tupac.tar && docker compose up -d --force-recreate"

---

🛠 Docker Management

• Check containers: docker ps
• Logs: docker logs tupac
• Stop: docker stop tupac
• Restart: docker start tupac
• Prune: docker system prune -a

---

🖥️ Systemd Integration (Recommended for RPi)

1. Copy the service file to your Pi:

   scp config/telegram-bot.service.ini pi@<PI_HOST>:/etc/systemd/system/telegram-bot.service

2. Enable and manage the service:

   sudo systemctl daemon-reload
   sudo systemctl enable telegram-bot
   sudo systemctl start telegram-bot
   sudo systemctl status telegram-bot
   sudo systemctl stop telegram-bot

• This ensures the bot starts on boot and restarts on failure.