Add comprehensive setup guide and Komodo configuration
Added: - SETUP_GUIDE.md: Complete step-by-step integration guide - komodo-gitea.config.toml: Gitea provider config snippet The guide covers: - Git provider configuration - Resource import options (Sync vs Manual) - Webhook setup with examples - Troubleshooting tips
This commit is contained in:
163
SETUP_GUIDE.md
Normal file
163
SETUP_GUIDE.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# Komodo + Gitea Integration Setup Guide
|
||||
|
||||
This guide will help you configure Komodo to work with your Gitea server.
|
||||
|
||||
## Summary
|
||||
|
||||
- **Gitea Host**: `gitea.straymoog.xyz`
|
||||
- **Gitea User**: `komodo`
|
||||
- **Gitea Token**: `18f8305e245023e8f5863991b66610854d6d9820`
|
||||
- **Komodo Host**: `komodo.internal`
|
||||
- **Repository**: `stray/komodo-demo`
|
||||
|
||||
## 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-demo-sync`
|
||||
- **Git Provider**: `gitea.straymoog.xyz`
|
||||
- **Git Account**: `stray` (or `komodo`)
|
||||
- **Repository**: `stray/komodo-demo`
|
||||
- **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-demo/settings/hooks`
|
||||
2. Click **Add Webhook** → **Gitea**
|
||||
3. Configure:
|
||||
- **Payload URL**: `http://komodo.internal:9120/listener/github/build/komodo-demo-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-demo-stack/deploy`
|
||||
|
||||
#### Resource Sync Webhook
|
||||
- **Payload URL**: `http://komodo.internal:9120/listener/github/sync/komodo-demo-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-demo-build`
|
||||
- Builds Docker image from Dockerfile
|
||||
- Image name: `komodo-demo-app:latest`
|
||||
- Triggers on push to `main` branch
|
||||
|
||||
### Stack Resource: `komodo-demo-stack`
|
||||
- Deploys using `docker-compose.yml`
|
||||
- Runs app on port 3000
|
||||
- Depends on built image
|
||||
|
||||
### Sync Resource: `komodo-demo-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).
|
||||
Reference in New Issue
Block a user