nuc/.artifacts/2026-02-01_21-06_gitea-coolify-integration.md

# Gitea-Coolify Integration for Auto-Deploy

**Date:** 2026-02-01 21:06
**Context:** Setting up Git auto-deploy from self-hosted Gitea to Coolify for Next.js applications

## Overview

This document describes how to configure Coolify to deploy applications from a self-hosted Gitea instance running on the same NUC server.

## Prerequisites

- Gitea running as a Coolify service (container: `gitea-ho0cwgcwos88cwc48g84c0g8`)
- Gitea SSH exposed on port 22222 (internal port 22)
- Repository already created in Gitea

## Key Issue: Network Isolation

Gitea runs on its own Docker network (`ho0cwgcwos88cwc48g84c0g8`), separate from Coolify's network (`coolify`). The Coolify helper container that clones repositories runs on the `coolify` network and cannot reach Gitea's internal SSH port.

### Solution: Connect Gitea to Coolify Network

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

This allows the Coolify helper to reach Gitea via container name on internal port 22.

## Step-by-Step Setup

### 1. Generate SSH Deploy Key

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

### 2. Add Private Key to Coolify

Via MCP:
```python
mcp__coolify__private_keys(
    action="create",
    name="Gitea Deploy Key",
    private_key="<contents of /tmp/coolify-gitea-key>"
)
```

Note the returned UUID (e.g., `akssgwowsccgwgoggs4ks8ck`).

### 3. Add Public Key to Gitea Repository

1. Navigate to Gitea repository → Settings → Deploy Keys
2. Add new key with contents of `/tmp/coolify-gitea-key.pub`
3. Title: "Coolify Deploy Key"

### 4. Connect Gitea to Coolify Network (Critical!)

```bash
ssh nuc "docker network connect coolify gitea-ho0cwgcwos88cwc48g84c0g8"
```

### 5. Create Application in Coolify

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

**Important:** Use the container name `gitea-ho0cwgcwos88cwc48g84c0g8` in the repository URL, NOT the IP address with port.

### 6. Configure Base Directory (if monorepo)

If your app is in a subdirectory, update via Laravel tinker:
```bash
docker exec coolify php artisan tinker --execute="
use App\Models\Application;
\$app = Application::where('uuid', '<app-uuid>')->first();
\$app->base_directory = '/path/to/app';
\$app->save();
"
```

For root directory, use `/`.

### 7. Set FQDN

Via MCP:
```python
mcp__coolify__application(
    action="update",
    uuid="<app-uuid>",
    fqdn="http://myapp.nuc.lan"
)
```

### 8. Deploy

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

## Repository URL Format

| Format | Works? | Notes |
|--------|--------|-------|
| `git@gitea-ho0cwgcwos88cwc48g84c0g8:user/repo.git` | ✅ Yes | Use container name (after network connect) |
| `git@192.168.1.3:user/repo.git` | ❌ No | Port 22 goes to NUC SSH, not Gitea |
| `ssh://git@192.168.1.3:22222/user/repo.git` | ❌ No | Coolify mangles ssh:// URLs |

## Troubleshooting

### "Permission denied (publickey)"
- Verify deploy key is added to both Coolify and Gitea
- Check that Gitea is connected to coolify network: `docker network inspect coolify | grep gitea`

### "Could not resolve hostname"
- Gitea not connected to coolify network
- Run: `docker network connect coolify gitea-ho0cwgcwos88cwc48g84c0g8`

### "Nixpacks failed to detect application type"
- Wrong base_directory setting
- Check repo structure matches base_directory path

### Build TypeScript errors
- Fix code locally, push to Gitea, redeploy

## Reference: Current Configuration

### Gitea Service UUID
`ho0cwgcwos88cwc48g84c0g8`

### Gitea Container Name
`gitea-ho0cwgcwos88cwc48g84c0g8`

### Gitea Ports
- HTTP: 3030 (external) → 3000 (internal)
- SSH: 22222 (external) → 22 (internal)

### Coolify Private Key UUID (for Gitea)
`akssgwowsccgwgoggs4ks8ck`

### Example Working Application
- **Name:** whyrating-brand
- **UUID:** r80gk0ccgg0okos8cw848kkk
- **Repository:** `git@gitea-ho0cwgcwos88cwc48g84c0g8:nuc/whyrating-brand.git`
- **FQDN:** http://brand.nuc.lan
- **Build Pack:** nixpacks
- **Port:** 3000

## Webhooks (Optional - For Auto-Deploy on Push)

To enable automatic deployments when pushing to Gitea:

1. Get the webhook URL from Coolify application settings
2. In Gitea: Repository → Settings → Webhooks → Add Webhook
3. Use the Coolify webhook URL with the secret

## Related Files

- SSH Private Key: Stored in Coolify (encrypted)
- SSH Public Key: Added to Gitea deploy keys