Deployment Guide

This guide covers deploying Solstice to production. You can deploy using a pre-compiled binary, build from source on a VPS, or run inside Docker.

Option 1: Pre-Compiled Binary (Easiest)

The fastest way to deploy Solstice is using the pre-compiled binary:

1. Download the latest solstice-release.zip from our Telegram Group.
2. Extract it on your server:

   unzip solstice-release.zip -d solstice
   cd solstice

3. Configure the environment:

   cp .env.example .env
   nano .env

4. Run the executable:

   ./solsticeio

---

Option 2: VPS Deployment (Recommended)

Requirements

• Ubuntu 22.04+ or Debian 12+ (x86_64 or ARM64)
• At least 1 vCPU, 1 GB RAM
• Go 1.24+ (Go 1.26 recommended), GCC (for CGo), Node.js 20+, FFmpeg 5+

Step-by-Step

1. Install System Dependencies

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

# Install build tools & CGo compiler
sudo apt install -y build-essential curl git unzip zlib1g-dev

# Install Go
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 Node.js (for yt-dlp JavaScript extraction)
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.26.x
ffmpeg -version # ffmpeg 5.x or 6.x
node -v         # v20.x

2. Clone and Build

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

# Compile the release binary with native CGo libntgcalls
./build.sh

3. Configure

cp .env.example .env
nano .env  # Fill in BOT_TOKEN, API_ID, API_HASH, SESSION_STRING, MONGO_URI, OWNER_ID

4. Running the Bot

Method A: Watchdog Script (Recommended)

start.sh automatically compiles if needed, runs the bot with process monitoring, and handles automatic crash recovery:

bash start.sh

Method B: Systemd Service (Production Daemon)

Create a systemd unit for automated 24/7 background operation:

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

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

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable solstice
sudo systemctl start solstice

View logs:

journalctl -u solstice -f

---

Option 3: Docker Deployment

Dockerfile

FROM golang:1.26-bookworm AS builder

# Install build tools and CGo dependencies
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 python:3.12-slim-bookworm

RUN apt-get update && apt-get install -y --no-install-recommends \
    ffmpeg \
    bash \
    gcc \
    curl \
    unzip \
    libcairo2 \
    ca-certificates \
    && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
    && apt-get install -y --no-install-recommends nodejs \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -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"]

docker-compose.yml

version: '3.8'

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

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

volumes:
  mongo-data:

networks:
  solstice-net:

---

Cloud Deployment (Railway, Render, VPS)

When deploying to cloud platforms:

1. Solstice listens for HTTP and WebSocket requests on PORT (defaulting to 8080).
2. Public URL is automatically detected if using platform domains (like Railway). For custom domains, set WEB_APP_URL=https://your-domain.com.
3. To bypass YouTube IP blocks, provide YOUTUBE_COOKIES in your environment.

---

Monitoring & Health Checks

Check	Command	Details
Ping	/ping	Bot latency, uptime, RAM, and CPU usage
HTTP Health	GET /health	Responds with JSON { "status": "ok", "service": "Solstice Room" }
Active streams	/ac	Active voice chat sessions count
Cookies	/checkcookies	YouTube cookie validity