Add operational documentation
CloudBeaver database manager guide, Ecija intranet deployment, Gitea-Coolify auto-deploy and integration docs, monitoring setup with presentation, remote access guide, security architecture, and Turbostarter deployment procedure. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Alejandro Gutiérrez
314
docs/gitea-coolify-integration.md
Normal file
314
docs/gitea-coolify-integration.md
Normal file
@@ -0,0 +1,314 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user