diff --git a/CI_CD_PIPELINE_SETUP_GUIDE.md b/CI_CD_PIPELINE_SETUP_GUIDE.md index f225aa1..6afa709 100644 --- a/CI_CD_PIPELINE_SETUP_GUIDE.md +++ b/CI_CD_PIPELINE_SETUP_GUIDE.md @@ -456,6 +456,8 @@ exit ### Step 3: Clone Repository for Registry Configuration +#### 3.1 Clone Repository + ```bash # Switch to CI_DEPLOY_USER (who has sudo access) sudo su - CI_DEPLOY_USER @@ -741,7 +743,7 @@ exit ### Step 6: Install Forgejo Actions Runner -#### 7.1 Download Runner +#### 6.1 Download Runner **Important**: Run this step as the **CI_DEPLOY_USER** (not root or CI_SERVICE_USER). The CI_DEPLOY_USER handles deployment tasks including downloading and installing the Forgejo runner. @@ -778,7 +780,7 @@ sudo mv forgejo-runner-${VERSION#v}-linux-amd64 /usr/bin/forgejo-runner **Production Recommendation**: Use version pinning in production environments to ensure consistency and avoid unexpected breaking changes. -#### 7.2 Register Runner +#### 6.2 Register Runner **Important**: The runner must be registered with your Forgejo instance before it can start. This creates the required `.runner` configuration file. @@ -937,7 +939,7 @@ sudo systemctl enable forgejo-runner.service - Enables the service to start automatically on boot - Sets up proper restart behavior for reliability -#### 7.3 Start Service +#### 6.3 Start Service ```bash # Start the Forgejo runner service @@ -954,7 +956,7 @@ sudo systemctl status forgejo-runner.service - The runner will now be available to accept and execute workflows from your Forgejo instance - The service will automatically restart if it crashes or the system reboots -#### 7.4 Test Runner Configuration +#### 6.4 Test Runner Configuration ```bash # Check if the runner is running @@ -982,7 +984,7 @@ sudo journalctl -u forgejo-runner.service -f --no-pager **Important**: This step sets up a Docker-in-Docker container that provides an isolated environment for CI/CD operations, eliminating resource contention with Harbor and simplifying cleanup. -#### 8.1 Create Containerized CI/CD Environment +#### 7.1 Create Containerized CI/CD Environment ```bash @@ -1013,7 +1015,7 @@ sudo docker exec ci-dind docker version **Why CI_DEPLOY_USER**: The CI_DEPLOY_USER handles deployment orchestration and has sudo access for Docker operations, following the principle of least privilege. -#### 8.2 Configure DinD for Harbor Registry +#### 7.2 Configure DinD for Harbor Registry ```bash @@ -1038,7 +1040,7 @@ sudo docker exec ci-dind docker rmi YOUR_CI_CD_IP:80/test/alpine:latest - **Tests connectivity**: Verifies DinD can pull, tag, and push images to Harbor - **Validates setup**: Ensures the complete CI/CD pipeline will work -#### 8.3 CI/CD Workflow Architecture +#### 7.3 CI/CD Workflow Architecture The CI/CD pipeline uses a three-stage approach with dedicated environments for each stage: @@ -1099,7 +1101,7 @@ docker exec ci-dind docker rmi YOUR_CI_CD_IP:80/test/dind-test:latest - Docker commands should work inside DinD - Harbor push/pull should work from DinD -#### 8.4 Production Deployment Architecture +#### 7.4 Production Deployment Architecture The production deployment uses a separate Docker Compose file (`docker-compose.prod.yml`) that pulls built images from the Harbor registry and deploys the complete application stack. @@ -1122,7 +1124,7 @@ The production deployment uses a separate Docker Compose file (`docker-compose.p - **🛡️ Rollback Capability**: Can easily rollback to previous image versions - **📊 Health Monitoring**: Built-in health checks for all services -#### 8.5 Monitoring Script +#### 7.5 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. @@ -1148,6 +1150,8 @@ chmod +x scripts/monitor.sh ### Step 8: Configure Firewall +#### 8.1 Configure UFW Firewall + ```bash sudo ufw --force enable sudo ufw default deny incoming @@ -1163,21 +1167,21 @@ sudo ufw allow 443/tcp # Harbor registry (public read access) ### Step 9: Test CI/CD Setup -#### 10.1 Test Docker Installation +#### 9.1 Test Docker Installation ```bash docker --version docker compose --version ``` -#### 10.2 Check Harbor Status +#### 9.2 Check Harbor Status ```bash cd /opt/APP_NAME/registry docker compose ps ``` -#### 10.3 Test Harbor Access +#### 9.3 Test Harbor Access ```bash # Test Harbor API @@ -1187,7 +1191,7 @@ curl -k https://localhost:8080/api/v2.0/health curl -k -I https://localhost ``` -#### 10.4 Get Public Key for Production Server +#### 9.4 Get Public Key for Production Server ```bash cat ~/.ssh/id_ed25519.pub @@ -1327,7 +1331,7 @@ sudo chmod +x /usr/local/bin/docker-compose ### Step 14: Configure Security -#### 15.1 Configure Firewall +#### 14.1 Configure Firewall ```bash sudo ufw --force enable @@ -1340,7 +1344,7 @@ sudo ufw allow 3000/tcp sudo ufw allow 3001/tcp ``` -#### 15.2 Configure Fail2ban +#### 14.2 Configure Fail2ban ```bash sudo systemctl enable fail2ban @@ -1349,7 +1353,7 @@ sudo systemctl start fail2ban ### Step 15: Create Application Directory -#### 16.1 Create Directory Structure +#### 15.1 Create Directory Structure ```bash sudo mkdir -p /opt/APP_NAME @@ -1358,7 +1362,7 @@ sudo chown PROD_SERVICE_USER:PROD_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`. -#### 16.2 Create SSL Directory (Optional - for domain users) +#### 15.2 Create SSL Directory (Optional - for domain users) ```bash sudo mkdir -p /opt/APP_NAME/nginx/ssl @@ -1663,13 +1667,13 @@ Go to your Forgejo repository and add these secrets in **Settings → Secrets an ### Step 21: Test Complete Pipeline -#### 22.1 Trigger a Test Build +#### 21.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 -#### 22.2 Verify Pipeline Steps +#### 21.2 Verify Pipeline Steps The pipeline should execute these steps in order: @@ -1682,7 +1686,7 @@ The pipeline should execute these steps in order: 7. **Push to Registry**: Push images to Harbor registry from DinD 8. **Deploy to Production**: Deploy to production server -#### 22.3 Check Harbor +#### 21.3 Check Harbor ```bash # On CI/CD Linode @@ -1696,7 +1700,7 @@ curl -k https://localhost:8080/v2/public/backend/tags/list curl -k https://localhost:8080/v2/public/frontend/tags/list ``` -#### 22.4 Verify Production Deployment +#### 21.4 Verify Production Deployment ```bash # On Production Linode @@ -1714,7 +1718,7 @@ docker compose logs backend docker compose logs frontend ``` -#### 22.5 Test Application Functionality +#### 21.5 Test Application Functionality 1. **Frontend**: Visit your production URL (IP or domain) 2. **Backend API**: Test API endpoints @@ -1723,7 +1727,7 @@ docker compose logs frontend ### Step 22: Set Up SSL/TLS (Optional - Domain Users) -#### 23.1 Install SSL Certificate +#### 22.1 Install SSL Certificate If you have a domain pointing to your Production Linode: @@ -1735,7 +1739,7 @@ sudo certbot --nginx -d your-domain.com sudo certbot certificates ``` -#### 23.2 Configure Auto-Renewal +#### 22.2 Configure Auto-Renewal ```bash # Test auto-renewal @@ -1749,7 +1753,7 @@ sudo crontab -e ### Step 23: Final Verification -#### 24.1 Security Check +#### 23.1 Security Check ```bash # Check firewall status @@ -1762,7 +1766,7 @@ sudo systemctl status fail2ban sudo grep "PasswordAuthentication" /etc/ssh/sshd_config ``` -#### 24.2 Performance Check +#### 23.2 Performance Check ```bash # Check system resources @@ -1775,7 +1779,7 @@ df -h docker system df ``` -#### 24.3 Backup Verification +#### 23.3 Backup Verification ```bash # Test backup script @@ -1788,14 +1792,14 @@ cd /opt/APP_NAME ### Step 24: Documentation and Maintenance -#### 25.1 Update Documentation +#### 24.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** -#### 25.2 Set Up Monitoring Alerts +#### 24.2 Set Up Monitoring Alerts ```bash # Set up monitoring cron job @@ -1805,7 +1809,7 @@ cd /opt/APP_NAME tail -f /tmp/monitor.log ``` -#### 25.3 Regular Maintenance Tasks +#### 24.3 Regular Maintenance Tasks **Daily:** - Check application logs for errors