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:

```bash
# 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

```yaml
# 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

```bash
# 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**
```bash
# 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**
```bash
# 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**: 
   ```bash
   cp .env.app.example .env     # Configure app environment
   cp .env.node.example .env    # Configure node environment
   ```
4. **Deploy App** (VPS):
   ```bash
   docker-compose -f docker-compose-app.yml up -d
   ```
5. **Deploy Node** (Home Server):
   ```bash
   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**:
```bash
# 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:

```bash
# 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:
```yaml
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:
```yaml
- 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:
```yaml
- 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.