Skip to content

DEPLOYMENT.md

Latest commit

 

History

History
122 lines (85 loc) · 3.88 KB

DEPLOYMENT.md

File metadata and controls

122 lines (85 loc) · 3.88 KB
Raw

CI/CD Deployment Setup

This repository includes a GitHub Actions workflow that automatically builds and deploys the application using Docker Compose.

The workflow uses appleboy/ssh-action and appleboy/scp-action for reliable SSH operations.

Required GitHub Secrets

To use the CI/CD pipeline, you need to configure the following secrets in your GitHub repository:

Setting up Secrets

Go to: Repository Settings → Secrets and variables → Actions → New repository secret

Add the following secrets:

Secret Name Description Required Example
SSH_PRIVATE_KEY Your SSH private key for server access ✅ Yes Contents of ~/.ssh/id_rsa
SSH_USER SSH username for the remote server ✅ Yes ubuntu or root
SSH_HOST IP address or hostname of your server ✅ Yes 192.168.1.100 or example.com
REMOTE_PROJECT_DIR Full path to the project directory on the server ✅ Yes /home/ubuntu/REFRAG-SYSTEM
SSH_PORT SSH port (defaults to 22 if not set) ❌ No 22 or 2222

How It Works

The workflow performs the following steps:

  1. Archive Source: Compresses the source code into a tar.gz file on the GitHub runnner (excluding .git and build artifacts).
  2. Transfer: Copies the source archive to your remote server using appleboy/scp-action.
  3. Deploy & Build: Connects via SSH (appleboy/ssh-action) to:
    • Extract the source code in the project directory.
    • Run docker compose down to stop existing containers.
    • Run docker compose up -d --build to build the Docker image on the server and start containers.

This approach minimizes disk usage on the GitHub runner by offloading the build process to your server.

Triggering the Workflow

The workflow runs automatically on:

  • Push to main or master branch
  • Manual trigger via GitHub Actions UI (workflow_dispatch)

Server Prerequisites

Your remote server must have:

  • Docker installed
  • Docker Compose installed (v2 recommended)
  • SSH access configured
  • The project directory created at REMOTE_PROJECT_DIR
  • A .env file in the project directory (if required by your application)

SSH Key Setup

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

ssh-keygen -t ed25519 -C "github-actions-deploy"

Copy Public Key to Server

ssh-copy-id -i ~/.ssh/id_ed25519.pub user@your-server

Add Private Key to GitHub Secrets

# Display your private key
cat ~/.ssh/id_ed25519

# Copy the entire output (including BEGIN and END lines) to GitHub Secrets

Testing the Deployment

  1. Make a change to your code
  2. Commit and push to the main branch
  3. Go to Actions tab in GitHub to monitor the deployment
  4. Check your server to verify the application is running

Troubleshooting

SSH Connection Issues

  • Verify SSH_PRIVATE_KEY is correctly formatted (includes header/footer)
  • Ensure the public key is in ~/.ssh/authorized_keys on the server
  • Check firewall rules allow SSH connections

Docker Issues

  • Verify Docker and Docker Compose are installed: docker --version && docker compose version
  • Check Docker daemon is running: sudo systemctl status docker
  • Ensure user has Docker permissions: sudo usermod -aG docker $USER

Deployment Failures

  • Check GitHub Actions logs for detailed error messages
  • Verify all secrets are correctly configured
  • Ensure .env file exists on the server if required
  • Check server disk space: df -h

Manual Deployment

If you need to deploy manually:

# SSH into your server
ssh user@your-server

# Navigate to project directory
cd /path/to/REFRAG-SYSTEM

# Pull latest changes (if using git on server)
git pull

# Rebuild and restart
docker compose down
docker compose up -d --build

# Check status
docker compose ps
docker compose logs -f