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

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

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

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

If running Komodo in Docker, mount the config file:
```bash
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:
```bash
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](https://komo.do).