major-domo-v2/.gitlab/DEPLOYMENT_SETUP.md

GitLab CI/CD Deployment Setup Guide

This guide will help you set up the complete CI/CD pipeline for Discord Bot v2.0.

---

📋 Prerequisites

• GitLab account (free tier)
• Docker Hub account
• SSH access to your Ubuntu VPS
• Git repository with Discord Bot v2.0 code

---

🚀 Step 1: GitLab Setup (5 minutes)

1.1 Create GitLab Project

# Option A: Mirror from existing GitHub repo
git remote add gitlab git@gitlab.com:yourusername/discord-bot.git
git push gitlab main

# Option B: Create new GitLab repo and push
# 1. Go to gitlab.com
# 2. Click "New Project"
# 3. Name it "discord-bot"
# 4. Set visibility to "Private"
# 5. Create project
# 6. Follow instructions to push existing repository

1.2 Add CI/CD Variables

Go to: Settings > CI/CD > Variables

Add the following variables (all marked as "Protected" and "Masked"):

Variable	Value	Description
DOCKER_USERNAME	your-docker-hub-username	Docker Hub login
DOCKER_PASSWORD	your-docker-hub-token	Docker Hub access token (NOT password)
SSH_PRIVATE_KEY	your-ssh-private-key	SSH key for VPS access (see below)
VPS_HOST	your.vps.ip.address	VPS IP or hostname
VPS_USER	your-vps-username	SSH username (usually ubuntu or root)

Important Notes:

• For DOCKER_PASSWORD: Use a Docker Hub access token, not your password
  • Go to hub.docker.com > Account Settings > Security > New Access Token
• For SSH_PRIVATE_KEY: Copy your entire private key including headers
  • cat ~/.ssh/id_rsa (or whatever key you use)
  • Include -----BEGIN OPENSSH PRIVATE KEY----- and -----END OPENSSH PRIVATE KEY-----

---

🔑 Step 2: SSH Key Setup for VPS

2.1 Generate SSH Key (if you don't have one)

# On your local machine
ssh-keygen -t ed25519 -C "gitlab-ci@discord-bot" -f ~/.ssh/gitlab_ci_bot

# Copy public key to VPS
ssh-copy-id -i ~/.ssh/gitlab_ci_bot.pub your-user@your-vps-host

2.2 Add Private Key to GitLab

# Copy private key
cat ~/.ssh/gitlab_ci_bot

# Paste entire output (including headers) into GitLab CI/CD variable SSH_PRIVATE_KEY

2.3 Test SSH Access

ssh -i ~/.ssh/gitlab_ci_bot your-user@your-vps-host "echo 'Connection successful!'"

---

🐳 Step 3: Docker Hub Setup

3.1 Create Access Token

1. Go to https://hub.docker.com/settings/security
2. Click "New Access Token"
3. Name: "GitLab CI/CD"
4. Permissions: "Read, Write, Delete"
5. Copy token immediately (you won't see it again!)

3.2 Create Repository

1. Go to https://hub.docker.com/repositories
2. Click "Create Repository"
3. Name: "discord-bot-v2"
4. Visibility: Private or Public (your choice)
5. Create

---

🖥️ Step 4: VPS Setup

4.1 Create Directory Structure

# SSH into your VPS
ssh your-user@your-vps-host

# Create production directory
sudo mkdir -p /opt/discord-bot
sudo chown $USER:$USER /opt/discord-bot
cd /opt/discord-bot

# Create staging directory (optional)
sudo mkdir -p /opt/discord-bot-staging
sudo chown $USER:$USER /opt/discord-bot-staging

4.2 Create docker-compose.yml (Production)

cd /opt/discord-bot
nano docker-compose.yml

Paste:

version: '3.8'

services:
  bot:
    image: yourusername/discord-bot-v2:latest
    container_name: discord-bot
    restart: unless-stopped
    env_file:
      - .env.production
    volumes:
      - ./logs:/app/logs
      - ./storage:/app/storage
    networks:
      - bot-network
    healthcheck:
      test: ["CMD", "python", "-c", "import discord; print('ok')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

  redis:
    image: redis:7-alpine
    container_name: discord-redis
    restart: unless-stopped
    volumes:
      - redis-data:/data
    networks:
      - bot-network

volumes:
  redis-data:

networks:
  bot-network:

4.3 Create Environment File

nano .env.production

Paste:

BOT_TOKEN=your_discord_bot_token
API_TOKEN=your_database_api_token
DB_URL=http://your-api-url:8000
GUILD_ID=your_discord_server_id
LOG_LEVEL=INFO
REDIS_URL=redis://redis:6379
REDIS_CACHE_TTL=300

4.4 Create Rollback Script

nano rollback.sh
chmod +x rollback.sh

Paste:

#!/bin/bash
set -e

COMPOSE_FILE="docker-compose.yml"
LOG_FILE="deployments.log"

echo "=== Discord Bot Rollback ==="
echo ""

# Show recent deployments
echo "Recent deployments:"
tail -n 10 $LOG_FILE | column -t -s '|'
echo ""

# Show current version
CURRENT=$(grep "image:" $COMPOSE_FILE | awk '{print $2}')
echo "Current version: $CURRENT"
echo ""

# Show last version
if [ -f .last_version ]; then
    LAST=$(cat .last_version)
    echo "Last version: $LAST"
    echo ""

    read -p "Rollback to this version? (y/N): " confirm
    if [ "$confirm" != "y" ]; then
        echo "Rollback cancelled."
        exit 0
    fi

    # Perform rollback
    echo "Rolling back..."
    sed -i "s|image:.*|image: $LAST|" $COMPOSE_FILE
    docker-compose up -d

    # Record rollback
    echo "$(date -Iseconds) | ROLLBACK | $LAST" >> $LOG_FILE

    echo "✅ Rollback complete!"
else
    echo "❌ No previous version found!"
    exit 1
fi

4.5 Initialize Deployment Log

touch deployments.log
echo "$(date -Iseconds) | INIT | Manual Setup" >> deployments.log

---

📁 Step 5: Update Project Files

5.1 Copy GitLab CI Configuration

# On your local machine, in project root
cp discord-app-v2/.gitlab-ci.yml .gitlab-ci.yml

# Update DOCKER_IMAGE variable with your Docker Hub username
sed -i 's/yourusername/YOUR_ACTUAL_USERNAME/' .gitlab-ci.yml

5.2 Update Dockerfile

# Replace existing Dockerfile with versioned one
cd discord-app-v2
mv Dockerfile Dockerfile.old
cp Dockerfile.versioned Dockerfile

5.3 Add Version Command to Bot

Edit discord-app-v2/bot.py and add:

import os

BOT_VERSION = os.getenv('BOT_VERSION', 'dev')
GIT_COMMIT = os.getenv('BOT_GIT_COMMIT', 'unknown')
BUILD_DATE = os.getenv('BOT_BUILD_DATE', 'unknown')

@bot.tree.command(name="version", description="Display bot version info")
async def version_command(interaction: discord.Interaction):
    embed = discord.Embed(
        title="🤖 Bot Version Information",
        color=0x00ff00
    )
    embed.add_field(name="Version", value=BOT_VERSION, inline=False)
    embed.add_field(name="Git Commit", value=GIT_COMMIT[:8], inline=True)
    embed.add_field(name="Build Date", value=BUILD_DATE, inline=True)

    await interaction.response.send_message(embed=embed, ephemeral=True)

---

🧪 Step 6: Test the Pipeline

6.1 Initial Commit

git add .
git commit -m "Setup GitLab CI/CD pipeline"
git push gitlab main

6.2 Watch Pipeline Execute

1. Go to GitLab project page
2. Click "CI/CD > Pipelines"
3. Watch your pipeline run:
   • ✅ Test stage should run
   • ✅ Build stage should run
   • ⏸️ Deploy stage waits for manual trigger

6.3 Manual Production Deploy

1. In GitLab pipeline view, find "deploy:production" job
2. Click the "Play" button ▶️
3. Watch deployment execute
4. Verify on VPS:

   ssh your-user@your-vps-host
   cd /opt/discord-bot
   docker-compose ps
   tail -f logs/discord_bot_v2.log
   

---

✅ Step 7: Verify Everything Works

7.1 Check Bot Status

# On VPS
docker-compose ps

# Should show:
# NAME              STATUS
# discord-bot       Up (healthy)
# discord-redis     Up

7.2 Check Version in Discord

In your Discord server:

/version

Should show something like:

Version: v2.1.1
Git Commit: a1b2c3d4
Build Date: 2025-01-19T10:30:00Z

7.3 Check Deployment Log

# On VPS
cat /opt/discord-bot/deployments.log

---

🔄 Step 8: Create Development Workflow

8.1 Create Develop Branch

git checkout -b develop
git push gitlab develop

8.2 Set Up Branch Protection (Optional)

In GitLab:

1. Settings > Repository > Protected Branches
2. Protect main: Require merge requests, maintainers can push
3. Protect develop: Developers can push

---

🎯 Usage Workflows

Regular Feature Development

# Create feature branch
git checkout -b feature/new-feature develop

# Make changes, commit
git add .
git commit -m "Add new feature"
git push gitlab feature/new-feature

# Merge to develop (auto-deploys to staging if configured)
git checkout develop
git merge feature/new-feature
git push gitlab develop

# After testing, merge to main
git checkout main
git merge develop
git push gitlab main

# In GitLab UI, manually trigger production deploy

Hotfix

# Create from main
git checkout -b hotfix/critical-bug main

# Fix and commit
git add .
git commit -m "Fix critical bug"
git push gitlab hotfix/critical-bug

# Merge to main
git checkout main
git merge hotfix/critical-bug
git push gitlab main

# Manually deploy in GitLab

Rollback

Option 1 - GitLab UI:

1. CI/CD > Pipelines
2. Find pipeline with working version
3. Click "Rollback" on deploy:production job

Option 2 - VPS Script:

ssh your-user@your-vps-host
cd /opt/discord-bot
./rollback.sh

Option 3 - Manual Job:

1. CI/CD > Pipelines > Latest
2. Click "Play" on rollback:production job

---

🐛 Troubleshooting

Pipeline Fails at Build Stage

Error: "Cannot connect to Docker daemon" Fix: GitLab runners need Docker-in-Docker enabled (already configured in .gitlab-ci.yml)

Error: "Permission denied for Docker Hub" Fix: Check DOCKER_USERNAME and DOCKER_PASSWORD variables are correct

Pipeline Fails at Deploy Stage

Error: "Permission denied (publickey)" Fix:

1. Check SSH_PRIVATE_KEY variable includes headers
2. Verify public key is in VPS ~/.ssh/authorized_keys
3. Test: ssh -i ~/.ssh/gitlab_ci_bot your-user@your-vps-host

Error: "docker-compose: command not found" Fix: Install docker-compose on VPS:

sudo apt-get update
sudo apt-get install docker-compose-plugin

Bot Doesn't Start on VPS

Check logs:

cd /opt/discord-bot
docker-compose logs -f bot

Common issues:

• Missing/wrong .env.production values
• Bot token expired
• Database API unreachable

---

📊 Version Bumping

Update version in .gitlab-ci.yml:

variables:
  VERSION_MAJOR: "2"
  VERSION_MINOR: "1"  # ← Change this for new features

Rules:

• Patch: Auto-increments each pipeline
• Minor: Manual bump for new features
• Major: Manual bump for breaking changes

---

🎓 What You Get

✅ Automated Testing: Every push runs tests ✅ Automated Builds: Docker images built on CI ✅ Semantic Versioning: v2.1.X format ✅ Manual Production Deploys: Approval required ✅ Automatic Rollback: On health check failure ✅ Quick Manual Rollback: 3 methods available ✅ Deployment History: Full audit trail ✅ Version Visibility: /version command

---

📞 Support

If you get stuck:

1. Check GitLab pipeline logs
2. Check VPS docker logs: docker-compose logs
3. Check deployment log: cat deployments.log
4. Verify all CI/CD variables are set correctly

---

Setup Time: ~30 minutes Deployment Time After Setup: ~2-3 minutes Rollback Time: ~1-2 minutes

You're all set! 🚀