nuc/docs/gitea-coolify-auto-deploy.md

# Gitea-Coolify Auto-Deploy Guide

Automatic deployment on git push using Coolify's manual webhook integration with self-hosted Gitea.

## Architecture

```
Developer → git push → Gitea → Webhook → Coolify → Build & Deploy
```

## Prerequisites

### 1. Deploy Key for Git Access

Apps use SSH deploy keys to pull code from Gitea:

| Resource | Value |
|----------|-------|
| **Deploy Key UUID** | `akssgwowsccgwgoggs4ks8ck` |
| **Gitea Container** | `gitea-ho0cwgcwos88cwc48g84c0g8` |
| **SSH Port** | 22222 (external) → 22 (internal) |

### 2. Network Connectivity

Gitea container must be on the `coolify` network:

```bash
docker network connect coolify gitea-ho0cwgcwos88cwc48g84c0g8
```

### 3. ⚠️ CRITICAL: Gitea Webhook Allowed Hosts

**Gitea blocks webhooks to internal hosts by default.** You MUST configure `ALLOWED_HOST_LIST` in Gitea's app.ini.

```bash
# Add [webhook] section to Gitea's app.ini
ssh nuc "docker exec gitea-ho0cwgcwos88cwc48g84c0g8 sh -c 'echo \"\" >> /data/gitea/conf/app.ini && echo \"[webhook]\" >> /data/gitea/conf/app.ini && echo \"ALLOWED_HOST_LIST = coolify,10.0.1.5,192.168.1.3,localhost,host.docker.internal,external\" >> /data/gitea/conf/app.ini'"

# Restart Gitea
ssh nuc "docker restart gitea-ho0cwgcwos88cwc48g84c0g8"

# Verify
ssh nuc "docker exec gitea-ho0cwgcwos88cwc48g84c0g8 cat /data/gitea/conf/app.ini | grep -A2 '\[webhook\]'"
```

**Without this, webhooks will fail with:**
```
dial tcp 10.0.1.5:8080: webhook can only call allowed HTTP servers
(check your webhook.ALLOWED_HOST_LIST setting), deny 'coolify(10.0.1.5:8080)'
```

### 4. ⚠️ CRITICAL: Use Internal Port 8080

**Coolify listens on port 8080 internally**, not 8000. Port 8000 is only the external Docker port mapping.

| Context | Port | URL Example |
|---------|------|-------------|
| From Docker network (Gitea webhook) | **8080** | `http://coolify:8080/webhooks/...` |
| From external/browser | 8000 | `http://192.168.1.3:8000` |

## Creating an App with Auto-Deploy

### Step 1: Create Application with Deploy Key

```python
mcp__coolify__application(
    action="create_key",
    name="my-app",
    project_uuid="a8484ggc88c40w4g4k004ow0",
    environment_name="production",
    server_uuid="qk84w0goo4w48g4ggsoo0oss",
    git_repository="git@gitea-ho0cwgcwos88cwc48g84c0g8:nuc/<repo>.git",
    git_branch="main",
    build_pack="nixpacks",
    ports_exposes="3000",
    private_key_uuid="akssgwowsccgwgoggs4ks8ck"
)
```

### Step 2: Configure FQDN

```bash
ssh nuc "docker exec coolify php artisan tinker --execute=\"
use App\Models\Application;
\\\$app = Application::where('uuid', '<app-uuid>')->first();
\\\$app->fqdn = 'http://<name>.nuc.lan';
\\\$app->custom_labels = null;
\\\$app->base_directory = '/';
\\\$app->save();
\""
```

### Step 3: Generate and Set Webhook Secret

```bash
# Generate a secret
SECRET=$(openssl rand -hex 32)
echo "Webhook Secret: $SECRET"

# Set in Coolify
ssh nuc "docker exec coolify php artisan tinker --execute=\"
use App\Models\Application;
\\\$app = Application::where('uuid', '<app-uuid>')->first();
\\\$app->manual_webhook_secret_gitea = '$SECRET';
\\\$app->save();
echo 'Set webhook secret for ' . \\\$app->name;
\""
```

### Step 4: Create Webhook in Gitea

1. Go to `http://192.168.1.3:3030/nuc/<repo>/settings/hooks`
2. Click **Add Webhook** → **Gitea**
3. Configure:
   - **Target URL:** `http://coolify:8080/webhooks/source/gitea/events/manual?uuid=<app-uuid>`
   - **Secret:** The secret generated in Step 3
   - **Trigger On:** Push Events
   - **Active:** ✓
4. Click **Add Webhook**

**⚠️ IMPORTANT:** The webhook URL MUST include `?uuid=<app-uuid>` - without it, Coolify won't know which app to deploy!

### Step 5: Initial Deploy

```python
mcp__coolify__deploy(tag_or_uuid="<app-uuid>")
```

### Step 6: Test Webhook

In Gitea webhook settings, click **Test Delivery**. Check:
- Response should be `200 OK`
- Coolify should show a new deployment queued

## Webhook URL Format

**Correct format (use port 8080 for internal Docker network):**
```
http://coolify:8080/webhooks/source/gitea/events/manual?uuid=<app-uuid>
```

| App | UUID | Webhook URL |
|-----|------|-------------|
| nuc-portal | `t80w0cw0oooc4g0soswos4so` | `http://coolify:8080/webhooks/source/gitea/events/manual?uuid=t80w0cw0oooc4g0soswos4so` |
| whyrating-hub | `vw4ggc40socwkgwg4osc8wg8` | `http://coolify:8080/webhooks/source/gitea/events/manual?uuid=vw4ggc40socwkgwg4osc8wg8` |
| whyrating-brand | `r80gk0ccgg0okos8cw848kkk` | `http://coolify:8080/webhooks/source/gitea/events/manual?uuid=r80gk0ccgg0okos8cw848kkk` |
| whyrating-templates | `qw80g4sog0kk8cc4wkcs8sgc` | `http://coolify:8080/webhooks/source/gitea/events/manual?uuid=qw80g4sog0kk8cc4wkcs8sgc` |

## Troubleshooting

### Webhook Returns "dial tcp ... webhook can only call allowed HTTP servers"

**Cause:** Gitea's webhook security blocks internal hosts by default.

**Fix:** Add Coolify to Gitea's allowed host list:

```bash
# Check current app.ini
ssh nuc "docker exec gitea-ho0cwgcwos88cwc48g84c0g8 cat /data/gitea/conf/app.ini | grep -A5 '\[webhook\]'"

# Edit app.ini to add:
[webhook]
ALLOWED_HOST_LIST = coolify,10.0.1.5,192.168.1.3,localhost,host.docker.internal,external

# Or allow all private IPs (less secure):
ALLOWED_HOST_LIST = private

# Restart Gitea
ssh nuc "docker restart gitea-ho0cwgcwos88cwc48g84c0g8"
```

### Webhook Returns 404 or No Deployment

**Cause:** Missing `?uuid=` parameter in webhook URL.

**Fix:** Ensure URL includes the app UUID:
```
http://coolify:8080/webhooks/source/gitea/events/manual?uuid=<app-uuid>
```

### Webhook Returns "Connection Refused" (dial tcp ... connection refused)

**Cause:** Using external port 8000 instead of internal port 8080.

**Fix:** Coolify's nginx listens on port **8080** inside the container, not 8000. Change:
```
# Wrong (external port)
http://coolify:8000/webhooks/...

# Correct (internal port)
http://coolify:8080/webhooks/...
```

### Webhook Returns 401 Unauthorized

**Cause:** Webhook secret mismatch.

**Fix:** Verify the secret matches in both Gitea and Coolify:
```bash
# Check Coolify
ssh nuc "docker exec coolify php artisan tinker --execute=\"
use App\Models\Application;
\\\$app = Application::where('uuid', '<app-uuid>')->first();
echo 'Secret: ' . \\\$app->manual_webhook_secret_gitea;
\""
```

### Webhook Delivers but Deployment Fails

Check Coolify logs:
```bash
ssh nuc "docker logs coolify 2>&1 | grep -i 'deploy\|webhook' | tail -30"
```

Common issues:
- Git pull fails: Check deploy key is added to repo
- Build fails: Check application logs in Coolify UI

## Current Configuration

### Shared Webhook Secret

All apps use the same webhook secret for simplicity:
```
9eb07a77964563378c5d66d99006e06ba3da39d232905d4b12554ff91ca39718
```

### Deploy Key (add to each new repo)

```
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGHtsL3jicJTsBekYuwbKjO0EcRadYKhvLSUw/36XF7h coolify-gitea
```

Add via Gitea: Repository → Settings → Deploy Keys → **Enable Write Access** ✓

## Why Not "Gitea Source"?

Coolify has a "Gitea Source" feature that attempts to use GitHub App-style OAuth. This **does not work well** with self-hosted Gitea because:

1. Gitea's OAuth2 is simpler than GitHub Apps (no JWT signing with private keys)
2. The credentials stored in Coolify are invalid/fake
3. Deployments fail with JWT parsing errors

**Use deploy keys + manual webhooks instead** - it's simpler and more reliable.

## References

- [Coolify CI/CD Gitea Integration](https://coolify.io/docs/applications/ci-cd/gitea/integration)
- [Gitea Webhooks Documentation](https://docs.gitea.com/usage/webhooks)
- [Gitea app.ini Cheat Sheet](https://docs.gitea.com/administration/config-cheat-sheet#webhook-webhook)