titan3d_react_node_sqllite/DEPLOYMENT_GUIDE.md

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

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:

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!