Deployment Guide

This guide covers deploying Solstice to production. You can choose to deploy the pre-compiled binary (easiest) or build from source.

Option 1: Pre-Compiled Binary (Easiest)

The fastest way to deploy Solstice without installing Go or Python is to use the pre-compiled binaries released in our Telegram group.

1. Download the latest solstice-release.zip from our Telegram Group.
2. Upload it to your VPS and extract it:

   unzip solstice-release.zip -d solstice
   cd solstice

3. Configure the environment variables:

   cp .env.example .env
   nano .env

4. Run the bot:

   ./solstice

---

Option 2: VPS Deployment (Recommended)

Requirements

• Ubuntu 22.04+ or Debian 12+ (any Linux will work)
• At least 1 vCPU, 1 GB RAM
• Go 1.20+, Python 3.9+, Node.js 18+, FFmpeg 5+

Step-by-Step

1. Install System Dependencies

# Update packages
sudo apt update && sudo apt upgrade -y

# Install Go
wget https://go.dev/dl/go1.22.5.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# Install Python 3
sudo apt install -y python3 python3-pip python3-venv

# Install Node.js (needed by yt-dlp)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Install FFmpeg
sudo apt install -y ffmpeg

# Verify installations
go version        # go1.22.5 linux/amd64
python3 --version # Python 3.11.x
node --version    # v20.x.x
ffmpeg -version   # ffmpeg version 6.x

2. Clone and Build

git clone https://github.com/SolsticeIO/SolsticeIO.git
cd SolsticeIO

# Install Python dependencies
pip3 install -r requirements.txt

# Build Go binary
go build -o solstice cmd/bot/main.go

3. Configure

cp .env.example .env
nano .env  # Fill in all required variables

4. Starting the Bot (Various Methods)

Depending on your server environment and workflow, choose one of the following methods to start Solstice:

Method A: Hybrid Watchdog Script (start.sh - Recommended)

The included start.sh script automatically checks dependencies, compiles the Go engine, launches the Python Voice Chat Daemon (internal/telegram/vc_daemon.py) alongside the Go bot, and handles automatic crash recovery & restarts:

bash start.sh

Method B: Running Manually via Separate Terminals

If you prefer running services separately for debugging or development:

1. Terminal 1 — Start the Python Voice Chat Daemon:

   python3 internal/telegram/vc_daemon.py

2. Terminal 2 — Start the Go Bot Engine:

   go run cmd/bot/main.go

   (or pre-compile and run: go build -o musicbot cmd/bot/main.go && ./musicbot)

Method C: Running via Screen or Tmux (Persistent VPS Session)

Keep the bot running in the background after closing your SSH session:

• Using screen:

  screen -S solstice
  bash start.sh
  # Press Ctrl+A then D to detach session
  
  # Re-attach anytime:
  screen -r solstice

• Using tmux:

  tmux new -s solstice
  bash start.sh
  # Press Ctrl+B then D to detach session
  
  # Re-attach anytime:
  tmux attach -t solstice

Method D: Systemd Background Service (24/7 Auto-Start on Server Boot)

Create a systemd unit file:

sudo nano /etc/systemd/system/solstice.service

[Unit]
Description=Solstice Telegram Music Bot Engine
After=network.target mongod.service

[Service]
Type=simple
User=your_username
WorkingDirectory=/home/your_username/SolsticeIO
EnvironmentFile=/home/your_username/SolsticeIO/.env
ExecStart=/bin/bash /home/your_username/SolsticeIO/start.sh
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Enable and start the service:

# Reload systemd manager & enable service
sudo systemctl daemon-reload
sudo systemctl enable solstice
sudo systemctl start solstice

# Check service status
sudo systemctl status solstice

# View real-time logs
journalctl -u solstice -f

---

Option 3: Docker Deployment

Dockerfile

FROM golang:1.22-alpine AS builder

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o solstice cmd/bot/main.go

FROM python:3.11-slim

# Install system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    ffmpeg \
    curl \
    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
    && apt-get install -y nodejs \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy remaining files
COPY . .

CMD ["bash", "start.sh"]

docker-compose.yml

version: '3.8'

services:
  solstice:
    build: .
    env_file: .env
    restart: unless-stopped
    depends_on:
      - mongodb
    networks:
      - solstice-net

  mongodb:
    image: mongo:7
    volumes:
      - mongo-data:/data/db
    networks:
      - solstice-net
    restart: unless-stopped

volumes:
  mongo-data:

networks:
  solstice-net:

# Build and start
docker compose up -d

# View logs
docker compose logs -f solstice

# Stop
docker compose down

---

CI/CD Pipeline

Solstice includes a GitHub Actions workflow that automatically builds and delivers releases.

File: .github/workflows/release.yml

Trigger

on:
  push:
    branches: [main]
    paths-ignore:
      - 'docs/**'
      - 'README.md'

Runs on every push to main that modifies code (ignores docs-only changes).

Pipeline Steps

1. Checkout Code
2. Set up Go 1.20
3. Set up Python 3.9
4. Install Python dependencies (pip + PyInstaller)
5. Build Go binary
   └── GOOS=linux GOARCH=amd64 go build -o release/musicbot cmd/bot/main.go
6. Build Python daemon (PyInstaller)
   └── pyinstaller --onefile --name vc_daemon_linux internal/telegram/vc_daemon.py
7. Package release
   └── Copy binary + daemon + docs + .env.example → release.zip
8. Send to Telegram
   └── Upload release.zip to a Telegram chat/channel via Bot API

Required Secrets

Secret	Description
TELEGRAM_BOT_TOKEN	Bot token for the release notification bot
TELEGRAM_CHAT_ID	Chat/channel ID to send the release archive to

Release Package Contents

release.zip
├── musicbot              # Compiled Go binary (linux/amd64)
├── vc_daemon_linux       # Compiled Python daemon (PyInstaller)
├── docs/                 # Documentation
└── .env.example          # Environment template

---

Updating

Manual Update

cd SolsticeIO
git pull origin main
go build -o solstice cmd/bot/main.go
pip3 install -r requirements.txt  # In case of new dependencies
sudo systemctl restart solstice

Automated Update (via CI/CD)

The GitHub Actions pipeline automatically builds and sends a release archive to your Telegram group. Download and extract to update.

---

MongoDB Hosting

Self-Hosted

sudo apt install -y mongodb-org
sudo systemctl enable mongod
sudo systemctl start mongod

Use MONGO_URI=mongodb://localhost:27017/solstice.

MongoDB Atlas (Cloud)

1. Create a free cluster at cloud.mongodb.com
2. Create a database user
3. Whitelist your server's IP (or use 0.0.0.0/0 for any)
4. Copy the connection string and set MONGO_URI

---

Monitoring

Logs

• systemd: journalctl -u solstice -f
• Docker: docker compose logs -f solstice
• Telegram: All errors and activities are logged to the LOGGER_ID group

Health Checks

Method	Command	What It Checks
Bot ping	/ping	Bot latency, uptime, RAM, CPU, PyTgCalls status
Cookie status	/checkcookies	YouTube cookie validity
Active streams	/ac	Number of active audio/video streams
Stats	/stats	Database size, served chats/users count

---

Security Considerations

• Session String: Treat the Pyrogram session string like a password. It grants full access to the associated Telegram account. Use a dedicated account.
• .env file: Never commit to Git. Add to .gitignore.
• MongoDB: Use authentication in production. Don't expose port 27017 publicly.
• Cookies: YouTube cookies contain session tokens. Rotate periodically and use /setcookies to update.
• Owner ID: The OWNER_ID has unrestricted bot access. Double-check this value.