# Titan3D Deployment Guide

This document outlines how to replicate the deployment architecture for Titan3D (or any future project using the same stack) when deploying to **Coolify** from a custom **Gitea** instance. 

By following this guide, you will bypass common proxy timeouts (e.g., `invalid index-pack output`, `early EOF`) and SSH port conflicts that arise when using Gitea Actions with Coolify.

---

## 1. The Tarball Bypass Checkout Strategy

When deploying a Docker container via Gitea Actions, standard `git clone` (either via `actions/checkout` or manually) can fail if your repository has a proxy timeout or a custom SSH port (e.g., 2222). 

Instead of fighting Git, we **bypass Git entirely** by using `curl` to instantly download an archive tarball from Gitea's internal API.

### Add this to your `.gitea/workflows/ci.yaml`

```yaml
name: Build and Deploy

on:
  push:
    branches:
      - master

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code securely via Tarball (Bypass Git/Proxy timeouts)
        run: |
          # 1. Download the latest tarball directly from Gitea's API
          # Replace 'mohanki/titan3d_react_node_sqllite' with your owner/repo
          curl -sL https://git.digifox.live/mohanki/titan3d_react_node_sqllite/archive/master.tar.gz -o source.tar.gz
          
          # 2. Extract the code directly into the workspace
          tar -xzf source.tar.gz --strip-components=1
          rm source.tar.gz

      - name: Login to Gitea Container Registry
        uses: docker/login-action@v2
        with:
          registry: git.digifox.live
          username: ${{ gitea.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
          
      - name: Build and push Image
        uses: docker/build-push-action@v4
        with:
          context: .
          push: true
          tags: git.digifox.live/mohanki/titan-web:latest
          file: Dockerfile
          
      # Trigger Coolify Webhook
      - name: Trigger Coolify Deployment
        run: |
          curl -s -X GET "${{ secrets.COOLIFY_WEBHOOK_URL }}"
```

---

## 2. Managing Large Files (The `.gitignore` Rule)

Git is fundamentally designed for source code, not large binary assets (e.g., 100MB 3D models or 50MB HDRI images). Pushing large files will eventually corrupt your git packfiles or cause your Gitea server's proxy to crash during fetch operations.

Always maintain a strict `.gitignore`:

```gitignore
node_modules/
dist/
build/
coverage/
.DS_Store
*.log
.env*
!.env.example

# Exclude large heavy assets
public/assets/models/
backend/uploads/
*.glb
*.gltf
```

**What if I already pushed large files?**
If you accidentally push a 150MB file, deleting it in a future commit **does not remove it from the Git history**. The repository size will permanently inflate. To truly purge it without using BFG Repo-Cleaner, delete the repository in Gitea and recreate it.

---

## 3. Coolify Integration

1. In Gitea, navigate to your repository **Settings > Secrets**.
2. Add a new secret named `COOLIFY_WEBHOOK_URL`.
3. In Coolify, navigate to your Application > Webhooks > **Deploy Webhook**.
4. Copy the URL and paste it into the Gitea secret.

When the Gitea Action finishes building and pushing your Docker image to `git.digifox.live`, it will ping Coolify. Coolify will then seamlessly pull the latest image and restart your container!