arc-frp/CI_CD_DOCUMENTATION.md

Forgejo Actions CI/CD Documentation

This document describes the Forgejo Actions workflows for building, testing, and deploying the FRP Manager application.

Workflow Overview

The CI/CD pipeline consists of several automated workflows:

1. Test and Lint (.forgejo/workflows/test.yml)

• Triggers: Push to main/develop, Pull Requests
• Purpose: Code quality, type checking, and security scanning
• Jobs:
  • test-app: TypeScript compilation and build testing for the app
  • test-node: TypeScript compilation and build testing for the node
  • lint-dockerfiles: Dockerfile linting with hadolint
  • security-scan: Vulnerability scanning with Trivy

2. Build App (.forgejo/workflows/build-app.yml)

• Triggers: Changes to app/ directory, releases
• Purpose: Build and push the FRP Manager app Docker image
• Features: Multi-platform builds (amd64, arm64), caching

3. Build Node (.forgejo/workflows/build-node.yml)

• Triggers: Changes to node/ directory, releases
• Purpose: Build and push the Home Server Agent Docker image
• Features: Multi-platform builds (amd64, arm64), caching

4. Build All (.forgejo/workflows/build-all.yml)

• Triggers: Push to branches, PRs, releases, manual dispatch
• Purpose: Intelligent building of both images with change detection
• Features:
  • Path-based change detection
  • Parallel builds when both projects change
  • Build summary generation

5. Deploy (.forgejo/workflows/deploy.yml)

• Triggers: Releases, manual dispatch
• Purpose: Create deployment packages for production
• Features:
  • Environment-specific deployments
  • Automated deployment package creation
  • Documentation generation

Container Registry

Images are published to GitHub Container Registry (GHCR):

• App: ghcr.io/YOUR_USERNAME/YOUR_REPO/frp-manager-app
• Node: ghcr.io/YOUR_USERNAME/YOUR_REPO/home-server-agent

Image Tags

• latest - Latest build from main branch
• main - Latest main branch build
• develop - Latest develop branch build
• v1.0.0 - Specific version tags (on releases)
• 1.0 - Major.minor tags (on releases)

Setup Requirements

1. Repository Secrets

The workflows require these secrets to be configured in your Forgejo repository:

# Container registry access (automatically provided by Forgejo/GitHub)
GITHUB_TOKEN  # Automatic, no setup needed

2. Repository Settings

1. Enable Actions: Ensure Forgejo Actions are enabled in repository settings
2. Container Registry: Enable package publishing permissions
3. Branch Protection: Consider protecting main branch with required status checks

3. Runner Requirements

Ensure your Forgejo instance has runners configured with:

• Docker support
• Multi-platform build capabilities (for arm64 builds)
• Sufficient storage for image caching

Workflow Triggers

Automatic Triggers

# Push to main/develop branches
push:
  branches: [ main, develop ]

# Pull requests to main
pull_request:
  branches: [ main ]

# Release creation
release:
  types: [ published ]

# Path-based triggers (Build All workflow)
paths:
  - 'app/**'
  - 'node/**'

Manual Triggers

# Manual workflow dispatch (via UI or API)
workflow_dispatch:
  inputs:
    environment:
      description: 'Environment to deploy to'
      required: true
      default: 'staging'
      type: choice
      options: [ staging, production ]

Build Process

1. Code Quality Checks

# TypeScript compilation
npx tsc --noEmit           # App
bunx tsc --noEmit         # Node

# Application builds
npm run build             # App
bun run build            # Node

# Dockerfile linting
hadolint Dockerfile

# Security scanning
trivy fs .

2. Docker Image Building

# Multi-platform builds
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --push \
  --tag ghcr.io/user/repo/app:latest \
  ./app

# With caching
--cache-from type=gha \
--cache-to type=gha,mode=max

3. Image Publishing

• Images are automatically pushed to GHCR
• Tags are generated based on branch/release
• Metadata labels are added for tracking

Deployment Process

1. Automated Deployment Package

When a release is created or deployment is manually triggered:

1. Image Building: Latest images are built and pushed
2. Package Creation: Deployment artifacts are created
3. Documentation: Deployment instructions are generated
4. Artifact Upload: Package is uploaded for download

2. Deployment Package Contents

frp-manager-deployment-v1.0.0.tar.gz
├── docker-compose-app.yml      # App deployment config
├── docker-compose-node.yml     # Node deployment config
├── .env.app.example           # App environment template
├── .env.node.example          # Node environment template
├── deploy.sh                  # Deployment script
└── README.md                  # Deployment instructions

3. Manual Deployment Steps

1. Download Package: Get the deployment artifact from the workflow run
2. Extract: tar -xzf frp-manager-deployment-v1.0.0.tar.gz
3. Configure:

   cp .env.app.example .env     # Configure app environment
   cp .env.node.example .env    # Configure node environment
   

4. Deploy App (VPS):

   docker-compose -f docker-compose-app.yml up -d
   

5. Deploy Node (Home Server):

   docker-compose -f docker-compose-node.yml up -d
   

Monitoring and Troubleshooting

1. Workflow Status

• Check workflow runs in the Actions tab
• View build logs for debugging
• Monitor image registry for published images

2. Common Issues

Build Failures:

# Check TypeScript errors
npx tsc --noEmit

# Check Docker build context
docker build --no-cache ./app

Image Push Failures:

• Verify GITHUB_TOKEN permissions
• Check registry connectivity
• Ensure package publishing is enabled

Deployment Issues:

• Verify environment variables
• Check image availability in registry
• Validate Docker Compose syntax

3. Local Testing

Test workflows locally before pushing:

# Test app build
cd app && npm run build

# Test node build  
cd node && bun run build

# Test Docker builds
docker build -t test-app ./app
docker build -t test-node ./node

Customization

1. Modify Triggers

Edit workflow files to change when builds occur:

on:
  push:
    branches: [ main, develop, feature/* ]  # Add feature branches
    paths:
      - 'app/**'
      - 'docs/**'  # Add documentation changes

2. Add Tests

Extend test workflows with actual test suites:

- name: Run unit tests
  run: npm test

- name: Run integration tests  
  run: npm run test:integration

3. Custom Deployment

Add deployment to your specific infrastructure:

- name: Deploy to Kubernetes
  run: kubectl apply -f k8s/

- name: Deploy via SSH
  run: |
    scp deployment.tar.gz user@server:/tmp/
    ssh user@server 'cd /tmp && ./deploy.sh'

Best Practices

1. Branch Strategy

• Use develop for integration testing
• Use main for production-ready code
• Create releases for versioned deployments

2. Image Management

• Tag releases with semantic versions
• Use latest tag sparingly
• Clean up old images periodically

3. Security

• Regularly update base images
• Monitor security scan results
• Use specific version tags in production

4. Performance

• Leverage build caching
• Use multi-stage Docker builds
• Optimize image sizes

This CI/CD setup provides a robust foundation for building, testing, and deploying the FRP Manager application with proper automation and quality gates.