diff --git a/CI_CD_PIPELINE_SETUP_GUIDE.md b/CI_CD_PIPELINE_SETUP_GUIDE.md index 570de27..ba88750 100644 --- a/CI_CD_PIPELINE_SETUP_GUIDE.md +++ b/CI_CD_PIPELINE_SETUP_GUIDE.md @@ -788,39 +788,7 @@ Your Harbor registry is now configured with the following access model: - ✅ **Role-based access control**: Different user roles (admin, developer, guest) - ✅ **Audit logs**: Complete trail of all operations -### Step 6: Test Harbor Setup - -#### 6.1 Verify Harbor Installation - -```bash -# Check if all Harbor containers are running -cd /opt/APP_NAME/harbor -docker compose ps - -# Test Harbor API (HTTPS) -curl -k https://localhost/api/v2.0/health - -# Test Harbor UI (HTTPS) -curl -k -I https://localhost - -# Expected output: HTTP/1.1 200 OK -``` - -**Important**: All Harbor services should show as "Up" in the `docker compose ps` output. The health check should return a JSON response indicating all services are healthy. - -#### 6.2 Test Docker Login - -```bash -# Test Docker login to Harbor -docker login YOUR_CI_CD_IP -# Enter: ci-user and your-secure-password -``` - -**Expected output**: `Login Succeeded` message. - -**If you get certificate errors**: Make sure you've completed Step 5.1.1 (Configure Docker to Trust Harbor Registry) and restarted Docker. - -#### 6.3 Troubleshooting Common Issues +#### 5.13 Troubleshooting Common Harbor Issues **Certificate Issues**: ```bash @@ -863,15 +831,15 @@ sudo update-ca-certificates sudo systemctl restart docker ``` -### Step 7: Set Up SSH for Production Communication +### Step 6: Set Up SSH for Production Communication -#### 7.1 Generate SSH Key Pair +#### 6.1 Generate SSH Key Pair ```bash ssh-keygen -t ed25519 -C "ci-cd-server" -f ~/.ssh/id_ed25519 -N "" ``` -#### 7.2 Create SSH Config +#### 6.2 Create SSH Config ```bash cat > ~/.ssh/config << 'EOF' @@ -886,9 +854,9 @@ EOF chmod 600 ~/.ssh/config ``` -### Step 8: Install Forgejo Actions Runner +### Step 7: Install Forgejo Actions Runner -#### 8.1 Download Runner +#### 7.1 Download Runner ```bash cd ~ @@ -897,7 +865,7 @@ chmod +x forgejo-runner-0.2.11-linux-amd64 sudo mv forgejo-runner-0.2.11-linux-amd64 /usr/local/bin/forgejo-runner ``` -#### 8.2 Create Systemd Service +#### 7.2 Create Systemd Service ```bash sudo tee /etc/systemd/system/forgejo-runner.service > /dev/null << 'EOF' @@ -918,14 +886,14 @@ WantedBy=multi-user.target EOF ``` -#### 8.3 Enable Service +#### 7.3 Enable Service ```bash sudo systemctl daemon-reload sudo systemctl enable forgejo-runner.service ``` -#### 8.4 Test Runner Configuration +#### 7.4 Test Runner Configuration ```bash # Check if the runner is running @@ -953,9 +921,9 @@ forgejo-runner list - Check network: Ensure the runner can reach your Forgejo instance - Restart service: `sudo systemctl restart forgejo-runner.service` -### Step 9: Set Up Monitoring and Cleanup +### Step 8: Set Up Monitoring and Cleanup -#### 9.1 Monitoring Script +#### 8.1 Monitoring Script **Important**: The repository includes a pre-configured monitoring script in the `scripts/` directory that can be used for both CI/CD and production monitoring. @@ -979,7 +947,7 @@ chmod +x scripts/monitor.sh **Note**: The repository script is more comprehensive and includes proper error handling, colored output, and support for both CI/CD and production environments. It automatically detects the environment and provides appropriate monitoring information. -#### 9.2 Cleanup Script +#### 8.2 Cleanup Script **Important**: The repository includes a pre-configured cleanup script in the `scripts/` directory that can be used for both CI/CD and production cleanup operations. @@ -1006,7 +974,7 @@ chmod +x scripts/cleanup.sh **Note**: The repository script is more comprehensive and includes proper error handling, colored output, dry-run mode, and support for both CI/CD and production environments. It automatically detects the environment and provides appropriate cleanup operations. -#### 9.3 Test Cleanup Script +#### 8.3 Test Cleanup Script ```bash # Create some test images to clean up @@ -1044,7 +1012,7 @@ docker network ls - Check registry access: `cd /opt/APP_NAME/registry && docker compose ps` - Run manually: `bash -x scripts/cleanup.sh` -#### 9.4 Set Up Automated Cleanup +#### 8.4 Set Up Automated Cleanup ```bash # Create a cron job to run cleanup daily at 3 AM using the repository script @@ -1060,7 +1028,7 @@ crontab -l - **Logging**: All cleanup output is logged to `/tmp/cleanup.log` - **What it cleans**: Unused Docker images, volumes, networks, and Harbor images -### Step 10: Configure Firewall +### Step 9: Configure Firewall ```bash sudo ufw --force enable @@ -1075,23 +1043,23 @@ sudo ufw allow 443/tcp # Harbor registry (public read access) - **SSH**: Restricted to your IP addresses - **All other ports**: Blocked -### Step 11: Test CI/CD Setup +### Step 10: Test CI/CD Setup -#### 11.1 Test Docker Installation +#### 10.1 Test Docker Installation ```bash docker --version docker compose --version ``` -#### 11.2 Check Harbor Status +#### 10.2 Check Harbor Status ```bash cd /opt/APP_NAME/registry docker compose ps ``` -#### 11.3 Test Harbor Access +#### 10.3 Test Harbor Access ```bash # Test Harbor API @@ -1101,7 +1069,7 @@ curl -k https://localhost:8080/api/v2.0/health curl -k -I https://localhost ``` -#### 11.4 Get Public Key for Production Server +#### 10.4 Get Public Key for Production Server ```bash cat ~/.ssh/id_ed25519.pub @@ -1113,15 +1081,15 @@ cat ~/.ssh/id_ed25519.pub ## Part 2: Production Linode Setup -### Step 12: Initial System Setup +### Step 11: Initial System Setup -#### 12.1 Update the System +#### 11.1 Update the System ```bash sudo apt update && sudo apt upgrade -y ``` -#### 12.2 Configure Timezone +#### 11.2 Configure Timezone ```bash # Configure timezone interactively @@ -1135,7 +1103,7 @@ date **Expected output**: After selecting your timezone, the `date` command should show the current date and time in your selected timezone. -#### 12.3 Configure /etc/hosts +#### 11.3 Configure /etc/hosts ```bash # Add localhost entries for both IPv4 and IPv6 @@ -1156,7 +1124,7 @@ cat /etc/hosts **Expected output**: The `/etc/hosts` file should show entries for `127.0.0.1`, `::1`, and your Linode's actual IP addresses all mapping to `localhost`. -#### 12.4 Install Essential Packages +#### 11.4 Install Essential Packages ```bash sudo apt install -y \ @@ -1174,9 +1142,9 @@ sudo apt install -y \ python3-certbot-nginx ``` -### Step 13: Create Users +### Step 12: Create Users -#### 13.1 Create the SERVICE_USER User +#### 12.1 Create the SERVICE_USER User ```bash # Create dedicated group for the service account @@ -1187,7 +1155,7 @@ sudo useradd -r -g SERVICE_USER -s /bin/bash -m -d /home/SERVICE_USER SERVICE_US echo "SERVICE_USER:$(openssl rand -base64 32)" | sudo chpasswd ``` -#### 13.2 Create the DEPLOY_USER User +#### 12.2 Create the DEPLOY_USER User ```bash # Create deployment user @@ -1196,7 +1164,7 @@ sudo usermod -aG sudo DEPLOY_USER echo "DEPLOY_USER:$(openssl rand -base64 32)" | sudo chpasswd ``` -#### 13.3 Verify Users +#### 12.3 Verify Users ```bash sudo su - SERVICE_USER @@ -1210,9 +1178,9 @@ pwd exit ``` -### Step 14: Install Docker +### Step 13: Install Docker -#### 14.1 Add Docker Repository +#### 13.1 Add Docker Repository ```bash curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg @@ -1220,28 +1188,28 @@ echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docke sudo apt update ``` -#### 14.2 Install Docker Packages +#### 13.2 Install Docker Packages ```bash sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin ``` -#### 14.3 Configure Docker for Service Account +#### 13.3 Configure Docker for Service Account ```bash sudo usermod -aG docker SERVICE_USER ``` -### Step 15: Install Docker Compose +### Step 14: Install Docker Compose ```bash sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose ``` -### Step 16: Configure Security +### Step 15: Configure Security -#### 16.1 Configure Firewall +#### 15.1 Configure Firewall ```bash sudo ufw --force enable @@ -1254,16 +1222,16 @@ sudo ufw allow 3000/tcp sudo ufw allow 3001/tcp ``` -#### 16.2 Configure Fail2ban +#### 15.2 Configure Fail2ban ```bash sudo systemctl enable fail2ban sudo systemctl start fail2ban ``` -### Step 17: Create Application Directory +### Step 16: Create Application Directory -#### 17.1 Create Directory Structure +#### 16.1 Create Directory Structure ```bash sudo mkdir -p /opt/APP_NAME @@ -1272,22 +1240,22 @@ sudo chown SERVICE_USER:SERVICE_USER /opt/APP_NAME **Note**: Replace `APP_NAME` with your actual application name. This directory name can be controlled via the `APP_NAME` secret in your Forgejo repository settings. If you set the `APP_NAME` secret to `myapp`, the deployment directory will be `/opt/myapp`. -#### 17.2 Create SSL Directory (Optional - for domain users) +#### 16.2 Create SSL Directory (Optional - for domain users) ```bash sudo mkdir -p /opt/APP_NAME/nginx/ssl sudo chown SERVICE_USER:SERVICE_USER /opt/APP_NAME/nginx/ssl ``` -### Step 18: Clone Repository and Set Up Application Files +### Step 17: Clone Repository and Set Up Application Files -#### 18.1 Switch to SERVICE_USER User +#### 17.1 Switch to SERVICE_USER User ```bash sudo su - SERVICE_USER ``` -#### 18.2 Clone Repository +#### 17.2 Clone Repository ```bash cd /opt/APP_NAME @@ -1300,7 +1268,7 @@ git clone https://your-forgejo-instance/your-username/APP_NAME.git . **Note**: Replace `your-forgejo-instance` and `your-username/APP_NAME` with your actual Forgejo instance URL and repository path. -#### 18.3 Create Environment File +#### 17.3 Create Environment File The repository doesn't include a `.env.example` file for security reasons. The CI/CD pipeline will create the `.env` file dynamically during deployment. However, for manual testing or initial setup, you can create a basic `.env` file: @@ -1326,7 +1294,7 @@ EOF **Important**: Replace `YOUR_CI_CD_IP` with your actual CI/CD Linode IP address and `your_secure_password_here` with a strong password. -#### 18.4 Configure Docker for Harbor Access +#### 17.4 Configure Docker for Harbor Access ```bash # Add the CI/CD Harbor registry to Docker's insecure registries @@ -1343,9 +1311,9 @@ sudo systemctl restart docker **Important**: Replace `YOUR_CI_CD_IP` with your actual CI/CD Linode IP address. -### Step 19: Set Up SSH Key Authentication +### Step 18: Set Up SSH Key Authentication -#### 19.1 Add CI/CD Public Key +#### 18.1 Add CI/CD Public Key ```bash # Create .ssh directory for SERVICE_USER @@ -1359,7 +1327,7 @@ chmod 600 ~/.ssh/authorized_keys **Important**: Replace `YOUR_CI_CD_PUBLIC_KEY` with the public key from the CI/CD Linode (the output from `cat ~/.ssh/id_ed25519.pub` on the CI/CD Linode). -#### 19.2 Test SSH Connection +#### 18.2 Test SSH Connection From the CI/CD Linode, test the SSH connection: @@ -1369,16 +1337,16 @@ ssh production **Expected output**: You should be able to SSH to the production server without a password prompt. -### Step 20: Test Production Setup +### Step 19: Test Production Setup -#### 20.1 Test Docker Installation +#### 19.1 Test Docker Installation ```bash docker --version docker compose --version ``` -#### 20.2 Test Harbor Access +#### 19.2 Test Harbor Access ```bash # Test pulling an image from the CI/CD Harbor registry @@ -1387,14 +1355,14 @@ docker pull YOUR_CI_CD_IP:8080/public/backend:latest **Important**: Replace `YOUR_CI_CD_IP` with your actual CI/CD Linode IP address. -#### 20.3 Test Application Deployment +#### 19.3 Test Application Deployment ```bash cd /opt/APP_NAME docker compose up -d ``` -#### 20.4 Verify Application Status +#### 19.4 Verify Application Status ```bash docker compose ps @@ -1411,9 +1379,9 @@ curl http://localhost:3001/health ## Part 3: Final Configuration and Testing -### Step 21: Configure Forgejo Repository Secrets +### Step 20: Configure Forgejo Repository Secrets -#### 21.1 Required Repository Secrets +#### 20.1 Required Repository Secrets Go to your Forgejo repository and add these secrets in **Settings → Secrets and Variables → Actions**: @@ -1429,16 +1397,16 @@ Go to your Forgejo repository and add these secrets in **Settings → Secrets an - `DOMAIN`: Your domain name (e.g., `example.com`) - `EMAIL`: Your email for SSL certificate notifications -#### 21.2 Configure Forgejo Actions Runner +#### 20.2 Configure Forgejo Actions Runner -##### 21.2.1 Get Runner Token +##### 20.2.1 Get Runner Token 1. Go to your Forgejo repository 2. Navigate to **Settings → Actions → Runners** 3. Click **"New runner"** 4. Copy the registration token -##### 21.2.2 Configure Runner +##### 20.2.2 Configure Runner ```bash # Switch to DEPLOY_USER on CI/CD Linode @@ -1457,14 +1425,14 @@ forgejo-runner register \ --no-interactive ``` -##### 21.2.3 Start Runner +##### 20.2.3 Start Runner ```bash sudo systemctl start forgejo-runner.service sudo systemctl status forgejo-runner.service ``` -##### 21.2.4 Test Runner Configuration +##### 20.2.4 Test Runner Configuration ```bash # Check if the runner is running @@ -1492,9 +1460,9 @@ forgejo-runner list - Check network: Ensure the runner can reach your Forgejo instance - Restart service: `sudo systemctl restart forgejo-runner.service` -### Step 22: Set Up Monitoring and Cleanup +### Step 21: Set Up Monitoring and Cleanup -#### 22.1 Monitoring Script +#### 21.1 Monitoring Script **Important**: The repository includes a pre-configured monitoring script in the `scripts/` directory that can be used for both CI/CD and production monitoring. @@ -1518,7 +1486,7 @@ chmod +x scripts/monitor.sh **Note**: The repository script is more comprehensive and includes proper error handling, colored output, and support for both CI/CD and production environments. It automatically detects the environment and provides appropriate monitoring information. -#### 22.2 Cleanup Script +#### 21.2 Cleanup Script **Important**: The repository includes a pre-configured cleanup script in the `scripts/` directory that can be used for both CI/CD and production cleanup operations. @@ -1545,7 +1513,7 @@ chmod +x scripts/cleanup.sh **Note**: The repository script is more comprehensive and includes proper error handling, colored output, dry-run mode, and support for both CI/CD and production environments. It automatically detects the environment and provides appropriate cleanup operations. -#### 22.3 Test Cleanup Script +#### 21.3 Test Cleanup Script ```bash # Create some test images to clean up @@ -1583,7 +1551,7 @@ docker network ls - Check registry access: `cd /opt/APP_NAME/registry && docker compose ps` - Run manually: `bash -x scripts/cleanup.sh` -#### 22.4 Set Up Automated Cleanup +#### 21.4 Set Up Automated Cleanup ```bash # Create a cron job to run cleanup daily at 3 AM using the repository script @@ -1599,15 +1567,15 @@ crontab -l - **Logging**: All cleanup output is logged to `/tmp/cleanup.log` - **What it cleans**: Unused Docker images, volumes, networks, and Harbor images -### Step 23: Test Complete Pipeline +### Step 22: Test Complete Pipeline -#### 23.1 Trigger a Test Build +#### 22.1 Trigger a Test Build 1. **Make a small change** to your repository (e.g., update a comment or add a test file) 2. **Commit and push** the changes to trigger the CI/CD pipeline 3. **Monitor the build** in your Forgejo repository → Actions tab -#### 23.2 Verify Pipeline Steps +#### 22.2 Verify Pipeline Steps The pipeline should execute these steps in order: @@ -1619,7 +1587,7 @@ The pipeline should execute these steps in order: 6. **Push to Registry**: Push images to your private registry 7. **Deploy to Production**: Deploy to production server -#### 23.3 Check Harbor +#### 22.3 Check Harbor ```bash # On CI/CD Linode @@ -1633,7 +1601,7 @@ curl -k https://localhost:8080/v2/public/backend/tags/list curl -k https://localhost:8080/v2/public/frontend/tags/list ``` -#### 23.4 Verify Production Deployment +#### 22.4 Verify Production Deployment ```bash # On Production Linode @@ -1651,16 +1619,16 @@ docker compose logs backend docker compose logs frontend ``` -#### 23.5 Test Application Functionality +#### 22.5 Test Application Functionality 1. **Frontend**: Visit your production URL (IP or domain) 2. **Backend API**: Test API endpoints 3. **Database**: Verify database connections 4. **Logs**: Check for any errors in application logs -### Step 24: Set Up SSL/TLS (Optional - Domain Users) +### Step 23: Set Up SSL/TLS (Optional - Domain Users) -#### 24.1 Install SSL Certificate +#### 23.1 Install SSL Certificate If you have a domain pointing to your Production Linode: @@ -1672,7 +1640,7 @@ sudo certbot --nginx -d your-domain.com sudo certbot certificates ``` -#### 24.2 Configure Auto-Renewal +#### 23.2 Configure Auto-Renewal ```bash # Test auto-renewal @@ -1684,9 +1652,9 @@ sudo crontab -e # 0 12 * * * /usr/bin/certbot renew --quiet ``` -### Step 25: Final Verification +### Step 24: Final Verification -#### 25.1 Security Check +#### 24.1 Security Check ```bash # Check firewall status @@ -1699,7 +1667,7 @@ sudo systemctl status fail2ban sudo grep "PasswordAuthentication" /etc/ssh/sshd_config ``` -#### 25.2 Performance Check +#### 24.2 Performance Check ```bash # Check system resources @@ -1712,7 +1680,7 @@ df -h docker system df ``` -#### 25.3 Backup Verification +#### 24.3 Backup Verification ```bash # Test backup script @@ -1723,16 +1691,16 @@ cd /opt/APP_NAME ./scripts/backup.sh ``` -### Step 26: Documentation and Maintenance +### Step 25: Documentation and Maintenance -#### 26.1 Update Documentation +#### 25.1 Update Documentation 1. **Update README.md** with deployment information 2. **Document environment variables** and their purposes 3. **Create troubleshooting guide** for common issues 4. **Document backup and restore procedures** -#### 26.2 Set Up Monitoring Alerts +#### 25.2 Set Up Monitoring Alerts ```bash # Set up monitoring cron job @@ -1742,7 +1710,7 @@ cd /opt/APP_NAME tail -f /tmp/monitor.log ``` -#### 26.3 Regular Maintenance Tasks +#### 25.3 Regular Maintenance Tasks **Daily:** - Check application logs for errors