Skip to content

Commit 4121001

Browse files
C-o-m-o-nC-o-m-o-n
committed
feat: Add automated Raspberry Pi deployment via GitHub Actions, setup scripts, and comprehensive documentation.
1 parent 681e7b7 commit 4121001

File tree

9 files changed

+850
-1
lines changed

9 files changed

+850
-1
lines changed

‎.env.example‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Example environment variables for ACT Bot
2+
# Copy this file to .env and fill in your actual values
3+
4+
# Discord Bot Token (get from https://discord.com/developers/applications)
5+
DISCORD_BOT_TOKEN=your_discord_bot_token_here
6+
7+
# Google Gemini AI API Key (get from https://aistudio.google.com/app/apikey)
8+
GEMINI_AI_API_KEY=your_gemini_api_key_here
9+
10+
# MongoDB Connection URI
11+
# For local development (default):
12+
MONGO_DB_URI=mongodb://localhost:1717
13+
14+
# For MongoDB Atlas (production):
15+
# MONGO_DB_URI=mongodb+srv://username:[email protected]/database?retryWrites=true&w=majority
16+
17+
# API Server URL (for FastAPI component)
18+
# Note: Change port if 8000 is in use by another application
19+
APP_SERVER_URL=http://localhost:8001

‎.github/workflows/deploy-pi.yml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
name: Deploy to Raspberry Pi
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
jobs:
9+
deploy:
10+
if: github.repository == 'Comon-tech/ACT'
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- name: Checkout repository
15+
uses: actions/checkout@v4
16+
17+
- name: Setup Tailscale
18+
uses: tailscale/github-action@v2
19+
with:
20+
oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
21+
oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
22+
tags: tag:ci
23+
24+
- name: Deploy to Raspberry Pi
25+
uses: appleboy/[email protected]
26+
with:
27+
host: ${{ secrets.PI_HOST }}
28+
username: ${{ secrets.PI_USER }}
29+
key: ${{ secrets.PI_SSH_KEY }}
30+
command_timeout: "20m"
31+
script: |
32+
APP_DIR="/home/comon/ACT"
33+
REPO_URL="https://github.com/Comon-tech/ACT.git"
34+
REMOTE="origin"
35+
BRANCH="main"
36+
37+
if [ ! -d "$APP_DIR" ]; then
38+
echo "Directory $APP_DIR does not exist. Creating and cloning..."
39+
mkdir -p "$APP_DIR"
40+
cd "$APP_DIR"
41+
git clone --depth 1 "$REPO_URL" .
42+
git checkout "$BRANCH"
43+
else
44+
cd "$APP_DIR"
45+
if [ ! -d ".git" ]; then
46+
echo "No git repo found, Re-cloning..."
47+
rm -rf *
48+
git clone --depth 1 "$REPO_URL" .
49+
git checkout "$BRANCH"
50+
else
51+
echo "Fetching and resetting..."
52+
git fetch "$REMOTE" "$BRANCH"
53+
git reset --hard "$REMOTE"/"$BRANCH"
54+
fi
55+
fi
56+
57+
echo "Restarting service..."
58+
sudo systemctl restart act-bot.service
59+
sleep 3
60+
sudo systemctl status act-bot.service --no-pager

‎README.md‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,18 @@ ACT (Assisstant of Comon Tech) is an AI-powered [Discord](http://discord.com) bo
5353
>
5454
> 💡 Virtual environments and dependencies are automatically installed when you run any UV command, such as `uv run`, `uv sync`, or `uv lock`. [Learn more about UV projects](https://docs.astral.sh/uv/guides/projects)
5555
56+
## 🏠 Home Server Deployment
57+
58+
For deploying to a Raspberry Pi or other home server, see the [Deployment Guide](./deployment/DEPLOYMENT.md).
59+
60+
Quick start:
61+
62+
```bash
63+
cd ~/ACT
64+
chmod +x deployment/setup-pi.sh
65+
./deployment/setup-pi.sh
66+
```
67+
5668
## ✈️ Deployment
5769

5870
1. Create and run a live **MongoDB** database using a service like [**MongoDB Atlas**](https://www.mongodb.com/cloud/atlas) and get the **connection string**.
@@ -81,7 +93,7 @@ ACT (Assisstant of Comon Tech) is an AI-powered [Discord](http://discord.com) bo
8193
DISCORD_BOT_TOKEN=PLACE_VALUE_HERE
8294
GEMINI_AI_API_KEY=PLACE_VALUE_HERE
8395
MONGO_DB_URI=mongodb://localhost:1717
84-
APP_SERVER_URL=http://localhost:8000
96+
APP_SERVER_URL=http://localhost:8001
8597
```
8698
8799
c. Run **application** for production:

‎deployment/DEPLOYMENT.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# ACT Bot Deployment Guide - Raspberry Pi 4
2+
3+
This guide covers deploying the ACT Discord bot to a Raspberry Pi 4 home server.
4+
5+
## 📋 Prerequisites
6+
7+
- Raspberry Pi 4 (ideally 4GB+ RAM)
8+
- Raspbian/Raspberry Pi OS installed
9+
- Internet connection
10+
- SSH access configured
11+
- GitHub repository access
12+
13+
## 🔐 SSH & Tailscale Setup for GitHub Actions
14+
15+
> [!NOTE] > **You already have Tailscale working!** Since you can `ssh comon@pi4` from different networks, we just need to set up GitHub Actions to use it too.
16+
17+
### Quick Setup Steps
18+
19+
Follow the detailed guide: [SSH_SETUP.md](./SSH_SETUP.md)
20+
21+
**TL;DR:**
22+
23+
1. Generate SSH key: `ssh-keygen -t ed25519 -f ~/.ssh/act-deploy`
24+
2. Copy to Pi: `ssh-copy-id -i ~/.ssh/act-deploy.pub comon@pi4`
25+
3. Get Pi's Tailscale IP: `ssh comon@pi4 "tailscale ip -4"`
26+
4. Set up GitHub secrets (see below)
27+
28+
### Required GitHub Secrets
29+
30+
Go to your repo → **Settings** → **Secrets and variables** → **Actions**:
31+
32+
| Secret Name | How to Get |
33+
| -------------------- | --------------------------------------------------------------------------------------------------- |
34+
| `PI_HOST` | Run on Pi: `tailscale ip -4` (will be like `100.x.x.x`) |
35+
| `PI_USER` | `comon` |
36+
| `PI_SSH_KEY` | Content of `~/.ssh/act-deploy` (private key) |
37+
| `TS_OAUTH_CLIENT_ID` | [Tailscale OAuth](https://login.tailscale.com/admin/settings/oauth) → Create OAuth client → Copy ID |
38+
| `TS_OAUTH_SECRET` | Same OAuth client → Copy Secret |
39+
40+
> [!TIP] > **Creating Tailscale OAuth Client:**
41+
>
42+
> 1. Go to https://login.tailscale.com/admin/settings/oauth
43+
> 2. Click **Generate OAuth Client**
44+
> 3. Add tag: `tag:ci`
45+
> 4. Copy the Client ID and Secret to GitHub secrets
46+
47+
## 🚀 Initial Setup
48+
49+
### 1. Run Setup Script
50+
51+
SSH into your Pi and run:
52+
53+
```bash
54+
cd ~
55+
git clone https://github.com/Comon-tech/ACT.git
56+
cd ACT
57+
chmod +x deployment/setup-pi.sh
58+
./deployment/setup-pi.sh
59+
```
60+
61+
### 2. Configure Environment Variables
62+
63+
Edit the `.env` file with your actual values:
64+
65+
```bash
66+
nano /home/comon/ACT/.env
67+
```
68+
69+
Required variables:
70+
71+
```env
72+
DISCORD_BOT_TOKEN=your_actual_bot_token
73+
GEMINI_AI_API_KEY=your_actual_gemini_key
74+
MONGO_DB_URI=mongodb atlas uri
75+
APP_SERVER_URL=http://localhost:8001
76+
```
77+
78+
> [!NOTE] > **Port 8001** is used instead of 8000 to avoid conflict with your other app.
79+
80+
### 3. Start MongoDB
81+
82+
```bash
83+
# Start MongoDB service
84+
sudo systemctl start mongodb
85+
86+
# Enable MongoDB to start on boot
87+
sudo systemctl enable mongodb
88+
```
89+
90+
### 4. Start the Bot
91+
92+
```bash
93+
# Start the service
94+
sudo systemctl start act-bot.service
95+
96+
# Check status
97+
sudo systemctl status act-bot.service
98+
99+
# View logs
100+
sudo journalctl -u act-bot.service -f
101+
```
102+
103+
## 🔄 Manual Deployment
104+
105+
To manually deploy updates:
106+
107+
```bash
108+
cd /home/comon/ACT
109+
git pull origin main
110+
sudo systemctl restart act-bot.service
111+
```
112+
113+
## 📊 Service Management
114+
115+
```bash
116+
# Start the bot
117+
sudo systemctl start act-bot.service
118+
119+
# Stop the bot
120+
sudo systemctl stop act-bot.service
121+
122+
# Restart the bot
123+
sudo systemctl restart act-bot.service
124+
125+
# Check status
126+
sudo systemctl status act-bot.service
127+
128+
# View logs (live)
129+
sudo journalctl -u act-bot.service -f
130+
131+
# View last 100 lines of logs
132+
sudo journalctl -u act-bot.service -n 100
133+
```
134+
135+
## 🔧 Troubleshooting
136+
137+
### Bot won't start
138+
139+
1. Check logs:
140+
141+
```bash
142+
sudo journalctl -u act-bot.service -n 50
143+
```
144+
145+
2. Verify environment variables:
146+
147+
```bash
148+
cat /home/comon/ACT/.env
149+
```
150+
151+
3. Test manually:
152+
```bash
153+
cd /home/comon/ACT
154+
uv run python main.py --bot --db
155+
```
156+
157+
### MongoDB connection issues
158+
159+
```bash
160+
# Check MongoDB status
161+
sudo systemctl status mongodb
162+
163+
# Check if MongoDB is listening
164+
sudo netstat -tlnp | grep 1717
165+
166+
# Start MongoDB if not running
167+
sudo systemctl start mongodb
168+
```
169+
170+
### Port conflict
171+
172+
If port 8001 is also taken, edit `.env` and change `APP_SERVER_URL`:
173+
174+
```env
175+
APP_SERVER_URL=http://localhost:8002
176+
```
177+
178+
Then restart the service.
179+
180+
### GitHub Actions can't connect
181+
182+
1. Verify Tailscale is running on Pi:
183+
184+
```bash
185+
ssh comon@pi4 "tailscale status"
186+
```
187+
188+
2. Verify you're using the correct Tailscale IP in `PI_HOST` secret:
189+
190+
```bash
191+
ssh comon@pi4 "tailscale ip -4"
192+
```
193+
194+
3. Check GitHub Actions logs for specific errors
195+
196+
4. Test SSH connection with the deployment key:
197+
198+
```bash
199+
ssh -i ~/.ssh/act-deploy comon@TAILSCALE_IP
200+
```
201+
202+
5. Verify Tailscale OAuth credentials are correct in GitHub secrets
203+
204+
## 🔒 Security Recommendations
205+
206+
1. **Use Tailscale** ✅ (you're already doing this!)
207+
2. **Use SSH keys only** (disable password authentication)
208+
3. **Keep system updated**: `sudo apt update && sudo apt upgrade`
209+
4. **Monitor logs regularly**: `sudo journalctl -u act-bot.service -f`
210+
5. **Rotate SSH keys periodically** (regenerate deployment keys every few months)
211+
212+
## 📝 Notes
213+
214+
- The bot will automatically restart on system boot
215+
- Logs are managed by systemd journal
216+
- MongoDB data is stored in the default location
217+
- The API component is optional (only needed for web integrations)

0 commit comments

Comments
 (0)