added forgejo stack

2025-12-16 10:39:28 +01:00 · 2025-12-16 10:39:28 +01:00 · 5be5493015
commit 5be5493015
parent 876cfd9ba0
1 changed files with 478 additions and 73 deletions
--- a/content/en/docs/components/orchestration/stacks/forgejo.md
+++ b/content/en/docs/components/orchestration/stacks/forgejo.md
@ -1,127 +1,532 @@
 ---
 title: "Forgejo"
 linkTitle: "Forgejo"
-weight: 40
-description: Forgejo
+weight: 30
+description: >
+  Self-hosted Git service with built-in CI/CD capabilities
 ---

-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TBD]
-* **Assignee**: [Name or Team]
-* **Status**: Draft
-* **Last Updated**: YYYY-MM-DD
-* **TODO**:
-  * [ ] Add detailed component description
-  * [ ] Include usage examples and code samples
-  * [ ] Add architecture diagrams
-  * [ ] Review and finalize content
-{{% /alert %}}
-
 ## Overview

-[Detailed description of the component - what it is, what it does, and why it exists]
+Forgejo is a self-hosted Git service that provides repository hosting, code collaboration, and integrated CI/CD workflows. As part of the Edge Developer Platform, Forgejo serves as the central code repository and continuous integration system, offering a complete DevOps platform with Git hosting, issue tracking, and automated build pipelines.
+
+The Forgejo stack deploys a Forgejo server instance with PostgreSQL database backend, MinIO object storage, and Forgejo Runners for executing CI/CD workflows.

 ## Key Features

-* [Feature 1]
-* [Feature 2]
-* [Feature 3]
-
-## Purpose in EDP
-
-[Explain the role this component plays in the Edge Developer Platform and how it contributes to the overall platform capabilities]
+* **Git Repository Hosting**: Full-featured Git server with web interface for code management
+* **Built-in CI/CD**: Forgejo Actions provide GitHub Actions-compatible workflow automation
+* **Issue Tracking**: Integrated project management with issues, milestones, and pull requests
+* **Container Registry**: Built-in Docker registry for container image storage
+* **Code Review**: Pull request workflows with inline comments and approval processes
+* **Scalable Runners**: Distributed runner architecture with Docker-in-Docker execution
+* **S3 Object Storage**: MinIO integration for artifacts, LFS objects, and backups

 ## Repository

-**Code**: [Link to source code repository]
+**Code**: [Forgejo Stack Templates](https://edp.buildth.ing/DevFW-CICD/stacks/src/branch/main/template/stacks/forgejo)

-**Documentation**: [Link to component-specific documentation]
+**Documentation**:
+* [Forgejo Official Documentation](https://forgejo.org/docs/latest/)
+* [Forgejo Actions Documentation](https://forgejo.org/docs/latest/user/actions/)
+* [Forgejo Helm Chart Repository](https://code.forgejo.org/forgejo-helm/forgejo-helm)

 ## Getting Started

 ### Prerequisites

-* [Prerequisite 1]
-* [Prerequisite 2]
+* Kubernetes cluster with ArgoCD installed (provided by `core` stack)
+* CloudNativePG operator (provided by `core` stack)
+* Ingress controller configured (provided by `otc` stack)
+* cert-manager for TLS certificate management (provided by `otc` stack)
+* Infrastructure deployed through [Infra Deploy](https://edp.buildth.ing/DevFW/infra-deploy)

 ### Quick Start

-[Step-by-step guide to get started with this component]
+The Forgejo stack is deployed as part of the EDP installation process:

-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
+1. **Trigger Deploy Pipeline**
+   - Go to [Infra Deploy Pipeline](https://edp.buildth.ing/DevFW/infra-deploy/actions?workflow=deploy.yaml)
+   - Click on Run workflow
+   - Enter a name in "Select environment directory to deploy". This must be DNS Compatible. (if you enter `test-me` then the domain will be `forgejo.test-me.t09.de`)
+   - Execute workflow
+
+2. **ArgoCD Synchronization**
+   ArgoCD automatically deploys:
+   - Forgejo server (Helm chart v12.0.0)
+   - PostgreSQL database cluster (CloudNativePG)
+   - Forgejo Runners with Docker-in-Docker execution
+   - Ingress configuration with TLS
+   - Database credentials and storage secrets

 ### Verification

-[How to verify the component is working correctly]
-
-## Usage Examples
-
-### [Use Case 1]
-
-[Example with code/commands showing common use case]
+Verify the Forgejo deployment:

 ```bash
-# Example commands
+# Check ArgoCD applications status
+kubectl get application forgejo-server -n argocd
+kubectl get application forgejo-runner -n argocd
+
+# Verify Forgejo server pods are running
+kubectl get pods -n gitea
+
+# Check PostgreSQL cluster status
+kubectl get cluster -n gitea
+
+# Verify Forgejo runners are active
+kubectl get pods -n gitea -l app=forgejo-runner
+
+# Verify ingress configuration
+kubectl get ingress -n gitea
 ```

-### [Use Case 2]
-
-[Another common scenario]
-
-## Integration Points
-
-* **[Component A]**: [How it integrates]
-* **[Component B]**: [How it integrates]
-* **[Component C]**: [How it integrates]
+Access the Forgejo web interface at `https://{DOMAIN_GITEA}`.

 ## Architecture

-[Optional: Add architectural diagrams and descriptions]
+### Component Architecture

-### Component Architecture (C4)
+The Forgejo stack consists of:

-[Add C4 Container or Component diagrams showing the internal structure]
+**Forgejo Server**:
+- Web application for Git repository management
+- API server for Git operations and CI/CD orchestration
+- Issue tracker and project management interface
+- Container registry for Docker images
+- Artifact storage via MinIO object storage

-### Sequence Diagrams
+**Forgejo Runners**:
+- 3-replica runner deployment for parallel job execution
+- Docker-in-Docker (DinD) architecture for containerized builds
+- Runner image: `code.forgejo.org/forgejo/runner:6.4.0`
+- Build container: `docker:28.0.4-dind`
+- Supports GitHub Actions-compatible workflows

-[Add sequence diagrams showing key interaction flows with other components]
+**Storage Architecture**:
+- 200Gi persistent volume for Git repositories (GPSSD storage)
+- OTC S3 object storage for LFS objects and artifacts
+- Encrypted volumes using KMS key integration
+- S3-compatible backup storage (100GB)

-### Deployment Architecture
-
-[Add infrastructure and deployment diagrams showing how the component is deployed]
+**Networking**:
+- SSH LoadBalancer service on port 32222 for Git operations
+- HTTPS ingress with TLS termination for web interface
+- Internal service communication via ClusterIP

 ## Configuration

-[Key configuration options and how to set them]
+### Forgejo Server Configuration
+
+The Forgejo server is configured through Helm values in `stacks/forgejo/forgejo-server/values.yaml`:
+
+**Application Settings**:
+- `FORGEJO_IMAGE_TAG`: Forgejo container image version
+- Application name: "EDP"
+- Slogan: "Build your thing in minutes"
+- User registration: Disabled by default
+- Email notifications: Enabled
+
+**Storage Configuration**:
+```yaml
+persistence:
+  size: 200Gi
+  storageClass: csi-disk
+  annotations:
+    everest.io/crypt-key-id: "{KMS_KEY_ID}"
+    everest.io/disk-volume-type: GPSSD
+```
+
+**Database Configuration**:
+Database credentials are sourced from Kubernetes secrets:
+- `POSTGRES_HOST`: PostgreSQL hostname
+- `POSTGRES_DB`: Database name
+- `POSTGRES_USER`: Database username
+- `POSTGRES_PASSWORD`: Database password
+- SSL verification enabled
+
+**Object Storage**:
+- Endpoint: `obs.eu-de.otc.t-systems.com`
+- Credentials from `gitea/forgejo-cloud-credentials` secret
+- Used for artifacts, LFS objects, and backups
+
+**External Services**:
+- Redis for caching and session management
+- Elasticsearch for issue indexing
+- SMTP for email notifications
+
+**SSH Configuration**:
+```yaml
+service:
+  ssh:
+    type: LoadBalancer
+    port: 32222
+```
+
+### Forgejo Runner Configuration
+
+Defined in `stacks/forgejo/forgejo-runner/dind-docker.yaml`:
+
+**Deployment Specification**:
+- 3 replicas for parallel execution
+- Runner version: 6.4.0
+- Docker DinD version: 28.0.4
+
+**Runner Registration**:
+- Offline registration using secret token
+- Instance URL from configuration
+- Predefined labels for Ubuntu 22.04 and latest
+
+**Container Configuration**:
+```yaml
+runner:
+  image: code.forgejo.org/forgejo/runner:6.4.0
+  privileged: true
+  securityContext:
+    runAsUser: 0
+    allowPrivilegeEscalation: true
+
+dind:
+  image: docker:28.0.4-dind
+  privileged: true
+  tlsCertDir: /certs
+```
+
+**Volume Management**:
+- Docker certificates volume for TLS communication
+- Runner data volume for registration and configuration
+- Shared socket for container communication
+
+### ArgoCD Application Configuration
+
+**Server Application** (`template/stacks/forgejo/forgejo-server.yaml`):
+- Name: `forgejo-server`
+- Namespace: `gitea`
+- Helm chart v12.0.0 from `https://code.forgejo.org/forgejo-helm/forgejo-helm.git`
+- Automated self-healing enabled
+- Values from `stacks-instances` repository
+
+**Runner Application** (`template/stacks/forgejo/forgejo-runner.yaml`):
+- Name: `forgejo-runner`
+- Namespace: `argocd`
+- Deployment manifests from `stacks-instances` repository
+- Automated sync with unlimited retries
+
+## Usage Examples
+
+### Creating Your First Repository
+
+After deployment, create and use Git repositories:
+
+1. **Access Forgejo Interface**
+   ```bash
+   open https://${DOMAIN_GITEA}
+   ```
+
+2. **Create a New Repository**
+   - Click "+" icon in top right
+   - Select "New Repository"
+   - Enter repository name and description
+   - Choose visibility (public/private)
+   - Initialize with README if desired
+
+3. **Clone and Push Code**
+   ```bash
+   # Clone the repository
+   git clone https://${DOMAIN_GITEA}/myorg/myrepo.git
+   cd myrepo
+
+   # Add your code
+   echo "# My Project" > README.md
+   git add README.md
+   git commit -m "Initial commit"
+
+   # Push to Forgejo
+   git push origin main
+   ```
+
+### Setting Up CI/CD with Forgejo Actions
+
+Create automated workflows using Forgejo Actions:
+
+1. **Create Workflow File**
+   ```bash
+   mkdir -p .forgejo/workflows
+   cat > .forgejo/workflows/build.yaml << 'EOF'
+   name: Build and Test
+
+   on:
+     push:
+       branches: [main]
+     pull_request:
+       branches: [main]
+
+   jobs:
+     build:
+       runs-on: ubuntu-22.04
+       steps:
+         - name: Checkout code
+           uses: actions/checkout@v4
+
+         - name: Set up Go
+           uses: actions/setup-go@v4
+           with:
+             go-version: '1.21'
+
+         - name: Build
+           run: go build -v ./...
+
+         - name: Test
+           run: go test -v ./...
+   EOF
+   ```
+
+2. **Commit and Push Workflow**
+   ```bash
+   git add .forgejo/workflows/build.yaml
+   git commit -m "Add CI/CD workflow"
+   git push origin main
+   ```
+
+3. **Monitor Workflow Execution**
+   - Navigate to repository in Forgejo web interface
+   - Click "Actions" tab
+   - View workflow runs and logs
+
+### Building and Publishing Container Images
+
+Use Forgejo to build and store Docker images:
+
+```yaml
+# .forgejo/workflows/docker.yaml
+name: Build Container Image
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Build image
+        run: |
+          docker build -t forgejo.${DOMAIN_GITEA}/myorg/myapp:${GITHUB_REF_NAME} .
+
+      - name: Login to registry
+        run: |
+          echo "${{ secrets.REGISTRY_PASSWORD }}" | \
+          docker login forgejo.${DOMAIN_GITEA} -u "${{ secrets.REGISTRY_USER }}" --password-stdin
+
+      - name: Push image
+        run: |
+          docker push forgejo.${DOMAIN_GITEA}/myorg/myapp:${GITHUB_REF_NAME}
+```
+
+### Using SSH for Git Operations
+
+Configure SSH access for Git operations:
+
+```bash
+# Generate SSH key if needed
+ssh-keygen -t ed25519 -C "your_email@example.com"
+
+# Add public key to Forgejo
+# Navigate to: Settings -> SSH / GPG Keys -> Add Key
+
+# Configure SSH host
+cat >> ~/.ssh/config << EOF
+Host forgejo.${DOMAIN_GITEA}
+  Port 32222
+  User git
+EOF
+
+# Clone repository via SSH
+git clone ssh://git@forgejo.${DOMAIN_GITEA}:32222/myorg/myrepo.git
+```
+
+## Integration Points
+
+* **Core Stack**: Depends on ArgoCD for deployment orchestration and CloudNativePG operator for database management
+* **OTC Stack**: Requires ingress-nginx controller and cert-manager for external access and TLS
+* **Coder Stack**: Development workspaces can clone repositories and trigger CI/CD workflows
+* **Observability Stack**: Prometheus metrics collection enabled via ServiceMonitor
+* **Dex (SSO)**: Can be configured for centralized authentication integration

 ## Troubleshooting

-### [Common Issue 1]
+### Forgejo Server Not Starting

-**Problem**: [Description]
+**Problem**: Forgejo server pods remain in `Pending` or `CrashLoopBackOff` state

-**Solution**: [How to fix]
+**Solution**:
+1. Check PostgreSQL cluster status:
+   ```bash
+   kubectl get cluster -n gitea
+   kubectl describe cluster -n gitea
+   ```

-### [Common Issue 2]
+2. Verify database credentials:
+   ```bash
+   kubectl get secret -n gitea | grep postgres
+   ```

-**Problem**: [Description]
+3. Check Forgejo server logs:
+   ```bash
+   kubectl logs -n gitea -l app=forgejo
+   ```

-**Solution**: [How to fix]
+4. Verify MinIO connectivity:
+   ```bash
+   kubectl get secret minio-credential -n gitea
+   kubectl logs -n gitea -l app=forgejo | grep -i minio
+   ```

-## Status
+### Cannot Access Forgejo Web Interface

-**Maturity**: [Production / Beta / Experimental]
+**Problem**: Forgejo web interface is not accessible at configured URL
+
+**Solution**:
+1. Verify ingress configuration:
+   ```bash
+   kubectl get ingress -n gitea
+   kubectl describe ingress -n gitea
+   ```
+
+2. Check TLS certificate status:
+   ```bash
+   kubectl get certificate -n gitea
+   kubectl describe certificate -n gitea
+   ```
+
+3. Verify DNS resolution:
+   ```bash
+   nslookup forgejo.${DOMAIN_GITEA}
+   ```
+
+4. Test service connectivity:
+   ```bash
+   kubectl port-forward -n gitea svc/forgejo-http 3000:3000
+   curl http://localhost:3000
+   ```
+
+### Git Operations Fail Over SSH
+
+**Problem**: Cannot clone or push repositories via SSH
+
+**Solution**:
+1. Verify SSH service is exposed:
+   ```bash
+   kubectl get svc -n gitea -l app=forgejo
+   ```
+
+2. Check LoadBalancer external IP:
+   ```bash
+   kubectl get svc -n gitea forgejo-ssh -o wide
+   ```
+
+3. Test SSH connectivity:
+   ```bash
+   ssh -T -p 32222 git@${DOMAIN_GITEA}
+   ```
+
+4. Verify SSH public key is added to Forgejo account
+
+### Forgejo Runners Not Executing Jobs
+
+**Problem**: CI/CD workflows remain queued or fail to execute
+
+**Solution**:
+1. Check runner pod status:
+   ```bash
+   kubectl get pods -n gitea -l app=forgejo-runner
+   kubectl logs -n gitea -l app=forgejo-runner
+   ```
+
+2. Verify runner registration:
+   ```bash
+   kubectl exec -n gitea -it deployment/forgejo-runner -- \
+     forgejo-runner status
+   ```
+
+3. Check Docker-in-Docker daemon:
+   ```bash
+   kubectl logs -n gitea -l app=forgejo-runner -c dind
+   ```
+
+4. Verify runner token secret exists:
+   ```bash
+   kubectl get secret -n gitea | grep runner
+   ```
+
+5. Check Forgejo server can communicate with runners:
+   ```bash
+   kubectl logs -n gitea -l app=forgejo | grep -i runner
+   ```
+
+### Database Connection Errors
+
+**Problem**: Forgejo cannot connect to PostgreSQL database
+
+**Solution**:
+1. Verify PostgreSQL cluster health:
+   ```bash
+   kubectl get pods -n gitea -l cnpg.io/cluster
+   kubectl logs -n gitea -l cnpg.io/cluster
+   ```
+
+2. Test database connection:
+   ```bash
+   kubectl exec -n gitea -it <postgres-pod> -- \
+     psql -U postgres -c "\l"
+   ```
+
+3. Verify database credentials secret:
+   ```bash
+   kubectl get secret -n gitea -o yaml | grep POSTGRES
+   ```
+
+4. Check database connection from Forgejo pod:
+   ```bash
+   kubectl exec -n gitea -it <forgejo-pod> -- \
+     nc -zv <postgres-host> 5432
+   ```
+
+### Storage Issues
+
+**Problem**: Repository pushes fail or object storage errors occur
+
+**Solution**:
+1. Check PVC status and capacity:
+   ```bash
+   kubectl get pvc -n gitea
+   kubectl describe pvc -n gitea
+   ```
+
+2. Verify MinIO credentials and connectivity:
+   ```bash
+   kubectl get secret minio-credential -n gitea
+   kubectl logs -n gitea -l app=forgejo | grep -i "s3\|minio"
+   ```
+
+3. Check available storage space:
+   ```bash
+   kubectl exec -n gitea -it <forgejo-pod> -- df -h
+   ```
+
+4. Review storage class configuration:
+   ```bash
+   kubectl get storageclass csi-disk -o yaml
+   ```

 ## Additional Resources

-* [Link to external documentation]
-* [Link to community resources]
-* [Link to related components]
-
-## Documentation Notes
-
-[Instructions for team members filling in this documentation - remove this section once complete]
+* [Forgejo Documentation](https://forgejo.org/docs/latest/)
+* [Forgejo Actions User Guide](https://forgejo.org/docs/latest/user/actions/)
+* [Forgejo Helm Chart Documentation](https://code.forgejo.org/forgejo-helm/forgejo-helm)
+* [Forgejo Runner Documentation](https://code.forgejo.org/forgejo/runner)
+* [CloudNativePG Documentation](https://cloudnative-pg.io/)
+* [ArgoCD Documentation](https://argo-cd.readthedocs.io/)