nuc/docs/gitea-coolify-integration.md

# Gitea-Coolify Integration for Git Auto-Deploy

Deploy Next.js applications from self-hosted Gitea with automatic deployments via Coolify.

## Overview

This guide covers deploying applications from Gitea (self-hosted Git) to Coolify with:
- SSH key authentication
- Automatic builds via Nixpacks
- Traefik routing with custom domains
- Optional webhooks for auto-deploy on push

## Architecture

```
Gitea (git@gitea-...:user/repo.git)
    ↓ SSH clone via deploy key
Coolify Helper Container
    ↓ Nixpacks build
Docker Image
    ↓ Deploy to coolify network
Running Container ← Traefik (*.nuc.lan routing)
```

## Prerequisites

- Gitea running as Coolify service
- Gitea container connected to `coolify` network
- SSH deploy key configured in both Coolify and Gitea

## Key References

| Resource | UUID/Value |
|----------|------------|
| **Server UUID** | `qk84w0goo4w48g4ggsoo0oss` |
| **Project UUID** | `a8484ggc88c40w4g4k004ow0` |
| **Environment** | `production` |
| **Deploy Key UUID** | `akssgwowsccgwgoggs4ks8ck` |
| **Gitea Container** | `gitea-ho0cwgcwos88cwc48g84c0g8` |
| **Gitea Service UUID** | `ho0cwgcwos88cwc48g84c0g8` |

### Gitea Ports

| Type | External | Internal |
|------|----------|----------|
| HTTP | 3030 | 3000 |
| SSH | 22222 | 22 |

## Network Configuration

### Critical: Connect Gitea to Coolify Network

Gitea runs on its own Docker network. The Coolify helper container clones repositories from the `coolify` network and cannot reach Gitea unless connected:

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

Verify connection:
```bash
docker network inspect coolify | grep gitea
```

### Repository URL Format

**Correct (use container name):**
```
git@gitea-ho0cwgcwos88cwc48g84c0g8:alezmad/repo-name.git
```

**Incorrect (will fail):**
```
git@192.168.1.3:alezmad/repo.git        # Port 22 goes to NUC SSH, not Gitea
ssh://git@192.168.1.3:22222/user/repo.git  # Coolify mangles ssh:// URLs
```

## Deploy Key Setup

### 1. Generate SSH Key (if needed)

```bash
ssh-keygen -t ed25519 -C "coolify-gitea" -f /tmp/coolify-gitea-key -N ""
```

### 2. Current Deploy Key

**Public Key (add to Gitea repos):**
```
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGHtsL3jicJTsBekYuwbKjO0EcRadYKhvLSUw/36XF7h coolify-gitea
```

**Coolify Private Key UUID:** `akssgwowsccgwgoggs4ks8ck`

### 3. Add Deploy Key to Gitea Repository

1. Navigate to: `http://192.168.1.3:3030/<user>/<repo>/settings/keys`
2. Click "Add Deploy Key"
3. Title: `Coolify Deploy Key`
4. Content: Paste the public key
5. **Enable Write Access** ✓ (required for pushing fixes)
6. Click "Add Deploy Key"

Or automate via Playwriter:
```javascript
await page.goto('http://192.168.1.3:3030/alezmad/<repo>/settings/keys');
await page.locator('button:has-text("Add Deploy Key")').click();
await page.locator('input[name="title"]').fill('Coolify Deploy Key');
await page.locator('textarea[name="content"]').fill('<public-key>');
await page.locator('input[name="is_writable"]').check();
await page.locator('#add-deploy-key-panel button.ui.primary.button').click();
```

## Deploying a New Application

### Step 1: Create Application in Coolify

```python
result = mcp__coolify__application(
    action="create_key",
    name="my-app-name",
    project_uuid="a8484ggc88c40w4g4k004ow0",
    environment_name="production",
    server_uuid="qk84w0goo4w48g4ggsoo0oss",
    git_repository="git@gitea-ho0cwgcwos88cwc48g84c0g8:alezmad/repo-name.git",
    git_branch="main",
    build_pack="nixpacks",
    ports_exposes="3000",
    private_key_uuid="akssgwowsccgwgoggs4ks8ck"
)
app_uuid = result['uuid']
```

### Step 2: Configure FQDN and Base Directory

The API doesn't allow setting FQDN directly. Use Laravel tinker:

```bash
docker exec coolify php artisan tinker --execute="
use App\Models\Application;
\$app = Application::where('uuid', '<app-uuid>')->first();
\$app->fqdn = 'http://myapp.nuc.lan';
\$app->custom_labels = null;  # Forces label regeneration
\$app->base_directory = '/';   # Or '/subdir' for monorepos
\$app->save();
echo 'FQDN: ' . \$app->fqdn;
"
```

### Step 3: Deploy

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

### Step 4: Monitor Deployment

```python
# Check deployment status
mcp__coolify__list_deployments(per_page=5)

# Get detailed logs
mcp__coolify__deployment(action="get", uuid="<deployment-uuid>", lines=50)
```

## Troubleshooting

### "Permission denied (publickey)"

**Cause:** Deploy key not authorized for the repository.

**Fix:**
1. Verify key is added to Gitea repository settings
2. Ensure "Enable Write Access" is checked
3. Verify Gitea is connected to coolify network

### "Could not resolve hostname"

**Cause:** Gitea container not on coolify network.

**Fix:**
```bash
docker network connect coolify gitea-ho0cwgcwos88cwc48g84c0g8
```

### "Nixpacks failed to detect application type"

**Cause:** Wrong `base_directory` setting.

**Fix:** Update via tinker:
```bash
docker exec coolify php artisan tinker --execute="
use App\Models\Application;
\$app = Application::where('uuid', '<uuid>')->first();
\$app->base_directory = '/';  # Adjust as needed
\$app->save();
"
```

### TypeScript Build Errors

**Common issue:** Missing function arguments (e.g., `Expected 6 arguments, but got 5`)

**Fix:**
1. Clone repo locally or on NUC
2. Fix the code
3. Commit and push to Gitea
4. Redeploy

Example fix workflow:
```bash
# On NUC
cd /tmp && git clone http://192.168.1.3:3030/alezmad/repo.git repo-fix
cd repo-fix
# Make fixes...
git add -A && git commit -m "Fix: description"

# Push using deploy key
cat > /tmp/gitea_key << 'EOF'
<private-key-content>
EOF
chmod 600 /tmp/gitea_key
git remote set-url origin ssh://git@localhost:22222/alezmad/repo.git
GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=no -i /tmp/gitea_key" git push origin main
```

### Traefik Labels Not Updated

**Cause:** FQDN changed but container labels still have old domain.

**Fix:** Clear custom_labels and redeploy:
```bash
docker exec coolify php artisan tinker --execute="
use App\Models\Application;
\$app = Application::where('uuid', '<uuid>')->first();
\$app->custom_labels = null;
\$app->save();
"
```

Then force redeploy:
```python
mcp__coolify__deploy(tag_or_uuid="<uuid>", force=True)
```

### 404 After Deployment

**Cause:** Traefik not routing to the new domain.

**Verify labels:**
```bash
container=$(docker ps --format '{{.Names}}' | grep <app-uuid-prefix> | head -1)
docker inspect $container --format '{{json .Config.Labels}}' | jq -r 'to_entries[] | select(.key | startswith("traefik")) | "\(.key)=\(.value)"' | grep rule
```

Should show: `Host(\`myapp.nuc.lan\`)`

## Webhooks (Auto-Deploy on Push)

### Setup Gitea Webhook

1. Get webhook URL from Coolify application settings
2. In Gitea: Repository → Settings → Webhooks → Add Webhook
3. Payload URL: Coolify webhook URL
4. Content type: `application/json`
5. Secret: From Coolify
6. Events: Push events

### Via MCP

```python
# Get application details (includes webhook info)
app = mcp__coolify__get_application(uuid="<uuid>")
# Webhook URL is in manual_webhook_secret_gitea field
```

## Current Deployed Applications

| Application | UUID | FQDN | Repository |
|-------------|------|------|------------|
| whyrating-brand | `r80gk0ccgg0okos8cw848kkk` | http://brand.nuc.lan | `alezmad/whyrating-brand` |
| whyrating-templates | `qw80g4sog0kk8cc4wkcs8sgc` | http://templates.nuc.lan | `alezmad/whyrating-templates` |

## Quick Reference Commands

### Check Application Status
```python
mcp__coolify__list_applications()
```

### View Logs
```python
mcp__coolify__application_logs(uuid="<uuid>", lines=50)
```

### Restart Application
```python
mcp__coolify__control(resource="application", action="restart", uuid="<uuid>")
```

### Force Redeploy
```python
mcp__coolify__deploy(tag_or_uuid="<uuid>", force=True)
```

### Check Container Status
```bash
docker ps --format 'table {{.Names}}\t{{.Status}}' | grep <uuid-prefix>
```

## Related Documentation

- `.artifacts/2026-02-01_21-06_gitea-coolify-integration.md` - Original setup notes
- `CLAUDE.md` - Quick reference section
- Coolify docs: https://coolify.io/docs