komodo/SETUP_GUIDE.md

Komodo + Gitea Integration Setup Guide

This guide will help you configure Komodo to work with your Gitea server.

Automated Setup (Recommended)

Gitea webhooks have already been configured automatically! To complete the Komodo setup, run the provided setup script:

Using Bash Script

# Ensure environment variables are set
export KOMODO_KEY="your-key"
export KOMODO_SECRET="your-secret"

# Run the setup script on a machine with access to Komodo
./setup-komodo.sh

Using Node.js Script

# Ensure environment variables are set
export KOMODO_KEY="your-key"
export KOMODO_SECRET="your-secret"

# Run the setup script (uses built-in fetch, no dependencies needed)
node setup-komodo.js

The automated setup will:

• ✓ Test connection to Komodo
• ✓ Create Build resource
• ✓ Create Resource Sync
• Configure git provider (requires config file - see below)

Webhooks Already Created

The following webhooks have been automatically configured in Gitea:

• ✓ Build webhook: http://komodo.internal:9120/listener/github/build/komodo-build/build
• ✓ Stack webhook: http://komodo.internal:9120/listener/github/stack/komodo-stack/deploy
• ✓ Sync webhook: http://komodo.internal:9120/listener/github/sync/komodo-sync/sync

---

Manual Setup (Alternative)

If you prefer to set up manually or need to customize the configuration, follow the steps below.

Summary

• Gitea Host: gitea.straymoog.xyz
• Gitea User: komodo
• Gitea Token: 18f8305e245023e8f5863991b66610854d6d9820
• Komodo Host: komodo.internal
• Repository: stray/komodo

Step 1: Configure Gitea Provider in Komodo

You need to add the Gitea git provider configuration to Komodo. There are two ways to do this:

Option A: Via Komodo Config File (Recommended)

Add this to your Komodo core.config.toml:

[[git_provider]]
domain = "gitea.straymoog.xyz"
accounts = [
  { username = "komodo", token = "18f8305e245023e8f5863991b66610854d6d9820" }
]

If running Komodo in Docker, mount the config file:

docker run -v ./core.config.toml:/config/core.config.toml \
  -e KOMODO_CONFIG_PATH=/config/core.config.toml \
  ghcr.io/moghtech/komodo:latest

Option B: Via Komodo UI

1. Navigate to Komodo UI at http://komodo.internal
2. Go to Settings → Git Providers
3. Add new provider:
   • Domain: gitea.straymoog.xyz
   • Username: komodo
   • Token: 18f8305e245023e8f5863991b66610854d6d9820

Step 2: Import Resources into Komodo

The repository contains Komodo resource definitions in .komodo/resources.toml. You can import them:

Option A: Using Resource Sync (Recommended - GitOps approach)

1. In Komodo UI, create a new Resource Sync:

   • Name: komodo-sync
   • Git Provider: gitea.straymoog.xyz
   • Git Account: stray (or komodo)
   • Repository: stray/komodo
   • Branch: main
   • Resource Path: .komodo

2. Execute the sync to import all resources (Build, Stack, Sync)

3. Enable webhook for automatic syncing on git push

Option B: Manual Creation

Create each resource manually in the Komodo UI using the configurations from .komodo/resources.toml.

Step 3: Set Up Webhooks in Gitea

Configure webhooks to trigger Komodo actions on git push.

Webhook Secret

First, ensure Komodo has a webhook secret configured. Check your Komodo environment for:

KOMODO_WEBHOOK_SECRET=your_secret_here

Create Webhooks

For each resource, create a webhook in Gitea:

Build Webhook

1. Go to https://gitea.straymoog.xyz/stray/komodo/settings/hooks
2. Click Add Webhook → Gitea
3. Configure:
   • Payload URL: http://komodo.internal:9120/listener/github/build/komodo-build/build
   • Content Type: application/json
   • Secret: Your KOMODO_WEBHOOK_SECRET
   • Trigger: Just the push event
   • Active: ✓

Stack Webhook (Deploy)

• Payload URL: http://komodo.internal:9120/listener/github/stack/komodo-stack/deploy

Resource Sync Webhook

• Payload URL: http://komodo.internal:9120/listener/github/sync/komodo-sync/sync

Note: Use /listener/github/ for Gitea (it's compatible with GitHub webhook format)

Step 4: Test the Integration

1. Make a small change to app.js (e.g., update the version)
2. Commit and push to the main branch
3. Watch Komodo:
   • Build should trigger automatically
   • Stack can be deployed with new image
   • Sync updates configuration if .komodo/resources.toml changes

Resource Details

Build Resource: komodo-build

• Builds Docker image from Dockerfile
• Image name: komodo-app:latest
• Triggers on push to main branch

Stack Resource: komodo-stack

• Deploys using docker-compose.yml
• Runs app on port 3000
• Depends on built image

Sync Resource: komodo-sync

• Syncs Komodo configuration from .komodo/ directory
• Enables GitOps workflow
• Can be configured to commit changes back to repo

Webhook URLs Reference

If using resource IDs instead of names, format:

http://komodo.internal:9120/listener/github/{resource_type}/{id_or_name}/{action}

Actions:

• Build: /build
• Stack: /deploy, /refresh
• Sync: /sync, /refresh
• Repo: /pull, /clone, /build

Troubleshooting

Webhook not triggering

• Check webhook secret matches KOMODO_WEBHOOK_SECRET
• Verify Komodo is accessible from Gitea server
• Check branch name matches resource configuration

Build fails

• Verify git provider credentials are correct
• Check build logs in Komodo UI
• Ensure builder/server has Docker installed

Cannot clone repository

• Verify git provider configuration in Komodo
• Check token has correct permissions
• Ensure komodo user has access to repository

Next Steps

1. Configure your Komodo core with Gitea provider
2. Import resources via Sync or manual creation
3. Set up webhooks for automated workflows
4. Test by pushing changes to the repository

For more information, see the Komodo documentation.