Deployment Guide

This guide covers deploying SolsticeIO to production. You can run SolsticeIO using Docker, run it directly on a Linux VPS with the included watchdog script, or manage it via systemd.

Prerequisites & System Requirements

• Operating System: Linux (Ubuntu 22.04+, Debian 12+, or Ubuntu 24.04 recommended; x86_64 or ARM64)
• Hardware: Minimum 1 vCPU, 1 GB RAM (2 GB RAM recommended for heavy voice streaming)
• Go Compiler: Go 1.24+ (Go 1.26 recommended), with gcc installed for CGo linking
• Node.js: Node.js 20+ or 22+ (required by yt-dlp to solve JavaScript challenges)
• FFmpeg: FFmpeg 5.x or 6.x
• Python: Python 3.10+ with yt-dlp installed
• Database: MongoDB 6.0+ instance (local or MongoDB Atlas)

---

Method 1: Docker Deployment (Recommended)

Docker provides an isolated, pre-configured environment including Node.js 22, FFmpeg, the bgutil YouTube POT (Proof of Origin) token provider, and the local telegram-bot-api server.

Repository Dockerfile

The repository includes a production multi-stage Dockerfile:

FROM golang:1.26-bookworm AS builder

RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    zlib1g-dev \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN if [ ! -f internal/vc/libntgcalls.a ] && [ -f internal/vc/libntgcalls.tar.gz ]; then \
    tar -xzf internal/vc/libntgcalls.tar.gz -C internal/vc; fi
RUN CGO_ENABLED=1 GOOS=linux go build -trimpath -ldflags="-w -s" -o solsticeio cmd/bot/main.go

FROM ubuntu:24.04

ENV DEBIAN_FRONTEND=noninteractive

# Install runtime dependencies: Python 3, FFmpeg, Node.js 22
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3 \
    python3-pip \
    python-is-python3 \
    curl \
    ca-certificates \
    && curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
    && apt-get install -y --no-install-recommends \
    ffmpeg \
    bash \
    procps \
    gcc \
    unzip \
    nodejs \
    wget \
    && rm -rf /var/lib/apt/lists/*

# Build bgutil-ytdlp-pot-provider for YouTube anti-bot token generation
RUN wget -qO /tmp/bgutil.zip https://github.com/Brainicism/bgutil-ytdlp-pot-provider/archive/master.zip \
    && unzip -q /tmp/bgutil.zip -d /root/ \
    && mv /root/bgutil-ytdlp-pot-provider-master /root/bgutil-ytdlp-pot-provider \
    && cd /root/bgutil-ytdlp-pot-provider/server \
    && npm ci \
    && npx tsc \
    && rm /tmp/bgutil.zip

# Install local telegram-bot-api binary
RUN wget -qO /usr/local/bin/telegram-bot-api https://github.com/jakbin/telegram-bot-api-binary/releases/download/latest/telegram-bot-api \
    && chmod +x /usr/local/bin/telegram-bot-api || echo "telegram-bot-api download skipped"

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir --break-system-packages -r requirements.txt

COPY --from=builder /app/solsticeio .
COPY internal/telegram/assets internal/telegram/assets
COPY strings strings
COPY start.sh .
COPY cookies.tx[t] ./cookies.txt
RUN chmod +x start.sh

EXPOSE 8080
CMD ["./start.sh"]

Running with Docker Compose

Create a docker-compose.yml file:

version: '3.8'

services:
  solsticeio:
    build: .
    env_file: .env
    ports:
      - "8080:8080"
    restart: unless-stopped
    depends_on:
      - mongodb

  mongodb:
    image: mongo:7.0
    restart: unless-stopped
    volumes:
      - mongo_data:/data/db

volumes:
  mongo_data:

Launch the container:

docker compose up -d --build
docker compose logs -f solsticeio

---

Method 2: VPS Bare Metal Deployment

1. Install System Packages (Ubuntu / Debian)

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential curl git unzip zlib1g-dev ffmpeg python3 python3-pip

# Install Node.js 22 (for yt-dlp JS challenge solving)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

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

# Install Python requirements (yt-dlp)
pip install --break-system-packages -r requirements.txt

2. Clone and Configure

git clone https://github.com/SolsticeIO/SolsticeIO.git
cd SolsticeIO
cp .env.example .env
nano .env  # Fill in your BOT_TOKEN, API_ID, API_HASH, SESSION_STRING, MONGO_URI, OWNER_ID

3. Launching with the Watchdog Script (start.sh)

start.sh handles startup prerequisites, launches a local Bot API server, compiles the binary with CGo, and runs a crash-recovery watchdog:

chmod +x start.sh
./start.sh

What start.sh does automatically:

1. Verifies that internal/vc/libntgcalls.a is extracted; if missing, extracts libntgcalls.tar.gz.
2. Compiles the Go binary: CGO_ENABLED=1 go build -trimpath -ldflags="-w -s" -o solsticeio cmd/bot/main.go.
3. If telegram-bot-api is present on PATH and API_ID/API_HASH are set, starts a local Telegram Bot API daemon on port 8081 (http://127.0.0.1:8081), setting BOT_API_URL to route requests locally.
4. Spawns solsticeio under a process supervisor that automatically restarts the bot upon unexpected exit codes, while halting gracefully on SIGINT or SIGTERM.

---

Method 3: Systemd Service (Production Daemon)

Create a systemd unit file to run SolsticeIO as a 24/7 background system service:

# /etc/systemd/system/solsticeio.service
[Unit]
Description=SolsticeIO Telegram Music Bot
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/root/SolsticeIO
ExecStart=/root/SolsticeIO/start.sh
Restart=always
RestartSec=5
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable solsticeio
sudo systemctl start solsticeio

View live logs:

journalctl -u solsticeio -f

---

Cloud Deployment (Railway, Render, VPS)

When deploying to cloud platforms:

1. Ports: SolsticeIO listens for HTTP and WebSocket connections on PORT (defaults to 8080).
2. Web Room Domain: For Railway deployments, RAILWAY_PUBLIC_DOMAIN is automatically detected to populate WEB_APP_URL. For custom domains, set WEB_APP_URL=https://your-domain.com.
3. Overcoming Cloud IP Blocks: Cloud server IPs (DigitalOcean, AWS, Hetzner, Railway) are frequently rate-limited by YouTube. Upload your YouTube cookies once via the in-bot /setcookies command. Cookies are persisted in MongoDB and loaded into memory on-the-fly.