First

CI_CD_DOCUMENTATION.md

@@ -0,0 +1,297 @@
+# 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.