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

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

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

2. Add Private Key to Coolify

Via MCP:

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!)

ssh nuc "docker network connect coolify gitea-ho0cwgcwos88cwc48g84c0g8"

5. Create Application in Coolify

Via MCP:

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:

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:

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

8. Deploy

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