introduced runner orchestration doc

.claude/CLAUDE.md

@@ -0,0 +1,74 @@
+# Technical Documentation Guidelines
+
+You are an expert technical writer with deep expertise in creating clear, concise, and well-structured documentation. Your goal is to produce documentation that flows naturally while maintaining technical accuracy.
+
+## Core Principles
+
+### 1. Conciseness and Clarity
+- Use clear, direct language
+- Eliminate unnecessary words and redundancy
+- Make every sentence count
+- Prefer active voice over passive voice
+- Use short paragraphs (3-5 sentences maximum)
+
+### 2. Structure and Organization
+- Start with the most important information
+- Use logical hierarchies with consistent heading levels
+- Group related concepts together
+- Provide clear navigation through table of contents when appropriate
+- Use lists for sequential steps or related items
+
+### 3. Flow and Readability
+- Ensure smooth transitions between sections
+- Connect ideas logically
+- Build complexity gradually
+- Use examples to illustrate concepts
+- Maintain consistent terminology throughout
+
+### 4. Technical Accuracy
+- Be precise with technical terms
+- Include relevant code examples that are tested and functional
+- Document edge cases and limitations
+- Provide accurate command syntax and parameters
+- Link to related documentation when appropriate
+
+## Documentation Structure
+
+### Standard Document Layout
+1. **Title** - Clear, descriptive heading
+2. **Overview** - Brief introduction (2-3 sentences)
+3. **Prerequisites** - What the reader needs to know or have
+4. **Main Content** - Organized in logical sections
+5. **Examples** - Practical, real-world use cases
+6. **Troubleshooting** - Common issues and solutions (when applicable)
+7. **Related Resources** - Links to additional documentation
+
+### Code Examples
+- Provide complete, runnable examples
+- Include comments for complex logic
+- Show expected output
+- Use consistent formatting and syntax highlighting
+
+### Commands and APIs
+- Show full syntax with all parameters
+- Indicate required vs optional parameters
+- Provide parameter descriptions
+- Include return values or output format
+
+## Writing Style
+
+- **Be direct**: "Configure the database" not "You should configure the database"
+- **Be specific**: "Set timeout to 30 seconds" not "Set an appropriate timeout"
+- **Be consistent**: Use the same terms for the same concepts
+- **Be complete**: Don't assume implicit knowledge; explain as needed
+
+## When Uncertain
+
+**If you don't know something or need clarification:**
+- Ask specific questions
+- Request examples or use cases
+- Clarify technical details or edge cases
+- Verify terminology and naming conventions
+- Confirm target audience and their expected knowledge level
+
+Your expertise is in writing excellent documentation. Use your judgment to create documentation that serves the reader's needs effectively. When in doubt, ask rather than guess.

content/en/docs/components/forgejo/actions/runner-orchestration.md

@@ -5,37 +5,29 @@ weight: 30
 description: GARM
 ---
 
-{{% alert title="Draft" color="warning" %}}
-**Editorial Status**: This page is currently being developed.
-
-* **Jira Ticket**: [TICKET-XXX](https://your-jira/browse/TICKET-XXX)
-* **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]
+GARM provides on-demand runner orchestration for Forgejo Actions through dynamic autoscaling. As Forgejo has similar API structure to Gitea (from which it was forked), GARM's Gitea/GitHub compatibility makes it a natural fit for automated runner provisioning. GARM supports custom providers, enabling runner infrastructure deployment across multiple cloud and infrastructure platforms.
+
+A custom edge-connect provider was implemented for GARM to enable infrastructure provisioning. Additionally, Forgejo was adapted to align more closely with Gitea's API, ensuring seamless integration with GARM's orchestration capabilities.
 
 ## Key Features
 
-* [Feature 1]
+* Autoscales Forgejo Actions runners dynamically based on workload demand
-* [Feature 2]
+* Leverages edge-connect infrastructure for distributed runner provisioning
-* [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]
+- Provides CI/CD infrastructure for all software development projects
+- Enhances the EDP platform capabilities through improved Forgejo automation
+- Enables teams to focus on development by consuming platform-managed runners without capacity planning concerns
 
 ## Repository
 
-**Code**: [Link to source code repository]
+**Code**:
+- [GARM Provider for Edge Connect](https://edp.buildth.ing/DevFW-CICD/garm-provider-edge-connect)
+- [GARM deploy script](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/scripts/local-helm.sh)
+- [GARM deploy manifests](https://edp.buildth.ing/DevFW/garm-deploy.git)
 
 **Documentation**: [Link to component-specific documentation]
 
@@ -43,20 +35,23 @@ description: GARM
 
 ### Prerequisites
 
-* [Prerequisite 1]
+* Container Runtime installed (e.g. docker)
-* [Prerequisite 2]
+* Forgejo, Gitea or Github
 
 ### Quick Start
 
-[Step-by-step guide to get started with this component]
+1. Clone the [GARM Provider repository](https://edp.buildth.ing/DevFW-CICD/garm-provider-edge-connect/)
-
+2. Build the Docker image: `docker buildx build -t <your-image-tag> .`
-1. [Step 1]
+3. Push the image to your container registry
-2. [Step 2]
+4. Deploy GARM using the [deployment script](https://edp.buildth.ing/DevFW/infra-deploy/src/branch/main/scripts/local-helm.sh) from the [infra-deploy](https://edp.buildth.ing/DevFW/infra-deploy) repository, targeting your Kubernetes cluster: `./local-helm.sh --garm`
-3. [Step 3]
 
 ### Verification
 
-[How to verify the component is working correctly]
+- Verify the GARM pod is running: `kubectl get pods -n garm`
+- Retrieve the GARM domain endpoint: `kubectl get ing -n garm`
+- Get the GARM admin password: `kubectl get secret -n garm garm-credentials -o json | jq .data.GARM_ADMIN_PASSWORD -r | base64 -d`
+- Configure endpoints, credentials, repositories, and runner pools in GARM as described in [TODO](TODO)
+
 
 ## Usage Examples
 
@@ -74,9 +69,8 @@ description: GARM
 
 ## Integration Points
 
-* **[Component A]**: [How it integrates]
+* **[Forgejo]**: Picks up pending action jobs, listen in Forgejo
-* **[Component B]**: [How it integrates]
+* **[Edge Connect]**: Uses this infrastructure to deploy runners that can pick up open jobs in forgejo
-* **[Component C]**: [How it integrates]
 
 ## Architecture
 
@@ -106,10 +100,123 @@ sequenceDiagram
     Runner->>Forgejo: Report Status
     GARM->>Runner: Terminate (Ephemeral)
 ```
+### Sequence Diagrams
+
+[Add sequence diagrams showing key interaction flows with other components]
+
+The diagram below shows how a trigger of an action results in deployment of a runner on edge-connect.
+
+```mermaid
+sequenceDiagram
+
+    rect rgb(255,200,200)
+    Forgejo->>GARM: (Webhook) A new job is pending
+    GARM->>GARM Provider Edge Connect: Create new runner
+    GARM Provider Edge Connect->>Edge Connect: Create App
+    GARM Provider Edge Connect->>Edge Connect: Create AppInstance
+    Edge Connect->>Runner: Deploys
+    end
+
+    Runner->>GARM: Retrieve runner registration token
+    GARM->>Forgejo: Retrieve runner registration token
+    Forgejo-->>GARM: Token
+    GARM-->>Runner: Token
+    Runner->>Forgejo: Register runner
+    Runner->>Forgejo: Fetch job
+    Runner->>Runner: Work on job
+    Runner->>Forgejo: Send result
+```
+
+### Deployment Architecture
+
+[Add infrastructure and deployment diagrams showing how the component is deployed]
+
+TODO c4
+
+- Garm Container in OTC Kubernetes
+- Garm-Provider in Garm Container
+- Garm in Garm container
+- EDP in OTC Kubernetes
+- Forgejo Runner in Edge Connect
+- EDP --notifies with webhook--> Garm
+- Garm --calls--> EDP
+- Garm --calls--> garm provider
+- garm provider --provisions instance--> Forgejo runner
+- Forgejo runner --retrieves bootstrap information-->Garm
+- Forgejo runner --picks up job--> EDP
 
 ## Configuration
 
-[Key configuration options and how to set them]
+### Provider Setup
+
+The config below configures an external provder for garm. Especially important is the `provider.external.config_file` which refers to the configuration of the external provider (example below) and `provider.external.provider_executable` which needs to point to the provider executable.
+
+
+```config.toml
+# config.toml
+...
+[[provider]]
+name = "edge-connect"
+description = "edge connect provider"
+provider_type = "external"
+
+[provider.external]
+config_file = "/etc/garm/edge-connect-provider-config.toml"
+provider_executable = "/opt/garm/providers.d/garm-provider-edge-connect"
+environment_variables = ["EDP_EDGE_CONNECT_"]
+```
+
+```edge-connect-provider-config.toml
+# edge-connect-provider-config.toml
+log_file = "/garm/provider.log"
+credentials_file = "/etc/garm-creds/credentials.toml" # to authenticate agains edge_connect.url
+
+[edge_connect]
+organization = "edp-developer-framework"
+region = "EU"
+url = "https://hub.apps.edge.platform.mg3.mdb.osc.live"
+default_flavor = "EU.small"
+
+[edge_connect.cloudlet]
+name = "Munich"
+organization = "TelekomOP"
+```
+
+```credentials.toml
+# credentials.toml for edge connect platform
+username = ""
+password = ""
+```
+
+### Runner Pool Configuration
+
+Once the configuration is in place and garm has been deployed. You can connect garm to Forgejo/Gitea/Github, using the commands below. If you have a forgejo instance, you want to create a gitea endpoint.
+
+```sh
+# https://edp.buildth.ing/DevFW/garm-deploy/src/branch/master/helm/garm/templates/init-job.yaml#L39-L56
+garm-cli init --name gitea --password ${GARM_ADMIN_PASSWORD} --username ${GARM_ADMIN_USERNAME} --email ${GARM_ADMIN_EMAIL} --url ${GARM_URL}
+if [ $? -ne 0 ]; then
+  echo "garm maybe already initialized"
+  exit 0
+fi
+
+# API_GIT_URL=https://garm-provider-test.t09.de/api/v1
+# GIT_URL=https://garm-provider-test.t09.de
+garm-cli gitea endpoint create \
+--api-base-url ${API_GIT_URL} \
+--base-url ${GIT_URL} \
+--description "My first Gitea endpoint" \
+--name local-gitea
+
+garm-cli gitea credentials add \
+--endpoint local-gitea \
+--auth-type pat \
+--pat-oauth-token $GITEA_TOKEN \
+--name autotoken \
+--description "Gitea token"
+```
+
+Now, connect to the WebUI, use `GARM_ADMIN_USERNAME` and `GARM_ADMIN_PASSWORD` as credentials to authenticate. Click on repositories and
 
 ## Troubleshooting
 
@@ -131,7 +238,7 @@ sequenceDiagram
 
 ## Additional Resources
 
-* [Link to external documentation]
+* [Using garm](https://github.com/cloudbase/garm/blob/main/doc/using_garm.md)
 * [Link to community resources]
 * [Link to related components]