Skip to content

TFGrid Gitea Guide

Self-hosted Git service with web interface - perfect for AI agent repositories and team collaboration.

Overview

TFGrid Gitea provides a lightweight, self-hosted Git service similar to GitHub but running on your ThreeFold Grid infrastructure. Ideal for storing code generated by tfgrid-ai-agent, private repositories, and team collaboration.

Features

  • 🔒 Self-hosted - Your code, your infrastructure, full control
  • 🌐 Web Interface - GitHub-like UI for browsing repos and managing projects
  • 🔑 User Management - Multiple users, organizations, and teams
  • 📝 Issues & PRs - Built-in issue tracking and pull requests
  • 🔗 API Access - Full RESTful API for automation
  • ðŸŠķ Lightweight - Runs efficiently on 2 cores, 2GB RAM
  • 🔐 Secure - Keep your code private on decentralized infrastructure

Quick Deployment

Option 1: Standalone Deployment

# Deploy Gitea on single VM
tfgrid-compose up tfgrid-gitea

# Get access information
tfgrid-compose address tfgrid-gitea

# Access at: http://<vm-ip>:3000

Deploy Gitea behind a gateway for SSL and custom domain:

# Deploy with gateway pattern
tfgrid-compose up tfgrid-gitea --pattern gateway --domain example.com

# Access at: https://example.com/gitea

Option 3: Full AI Dev Stack

Deploy AI agent + Gateway + Gitea together:

# Complete integrated workflow
tfgrid-compose up ai-gateway-stack --domain example.com

# Access:
# - example.com/gitea → Gitea UI
# - example.com/website1 → AI-generated sites

Default Credentials

⚠ïļ Important: Change these immediately after first login!

  • Username: gitadmin
  • Password: changeme123
  • Email: admin@localhost

Changing Admin Password

  1. Login to Gitea web interface
  2. Click your avatar → Settings
  3. Navigate to Account → Change Password
  4. Save new password

Using with AI Agent

Perfect companion for tfgrid-ai-agent - automatically store generated code in Gitea:

Setup Git Remote

# SSH to AI agent VM
tfgrid-compose ssh ai-gateway-stack --vm ai-agent

# Configure git
git config --global user.name "AI Agent"
git config --global user.email "ai@example.com"

# Create and push project
cd /home/developer/code
mkdir my-website && cd my-website
git init
git remote add origin http://example.com/gitea/gitadmin/my-website.git
git add .
git commit -m "Initial commit"
git push -u origin main

Automated Workflow

Coming in v0.11.0 - AI agent automatically: 1. Creates code 2. Pushes to Gitea (example.com/gitea/repos/projectname) 3. Deploys to gateway (example.com/projectname) 4. Complete visibility of all changes

API Usage

Gitea provides a full RESTful API for automation:

Generate API Token

  1. Login to Gitea
  2. Settings → Applications
  3. Generate New Token
  4. Copy token (shown only once!)

API Examples

# Create repository
curl -X POST "http://example.com/gitea/api/v1/user/repos" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"new-repo","description":"My new repository","private":false}'

# List repositories
curl "http://example.com/gitea/api/v1/user/repos" \
  -H "Authorization: token YOUR_TOKEN"

# Get repository info
curl "http://example.com/gitea/api/v1/repos/gitadmin/my-repo" \
  -H "Authorization: token YOUR_TOKEN"

# Create issue
curl -X POST "http://example.com/gitea/api/v1/repos/gitadmin/my-repo/issues" \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Bug found","body":"Description of the bug"}'

Full API docs available at: http://your-gitea/api/swagger

Configuration

Custom Settings

Set environment variables before deployment:

export GITEA_ADMIN_USER=myadmin
export GITEA_ADMIN_PASSWORD=mysecurepassword
export GITEA_ADMIN_EMAIL=admin@example.com
export GITEA_DOMAIN=example.com
export GITEA_PORT=3000

tfgrid-compose up tfgrid-gitea

Resource Requirements

Minimum: - 2 CPU cores - 2 GB RAM - 25 GB disk

Recommended: - 2 CPU cores - 4 GB RAM - 50 GB disk (for multiple large repos)

Gateway Integration

When deployed with the gateway pattern, Gitea is automatically proxied:

# Gateway automatically configures nginx:
location /gitea/ {
    proxy_pass http://gitea-vm:3000/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Benefits: - SSL/TLS encryption via Let's Encrypt - Custom domain support - No port specification needed - Professional URL: https://example.com/gitea

User Management

Creating Users

Via Web UI: 1. Login as admin 2. Site Administration → User Accounts 3. Create New Account 4. Fill in details and save

Via CLI: 

# SSH to Gitea VM
tfgrid-compose ssh tfgrid-gitea

# Create user
su - git -c "gitea admin user create \
  --username newuser \
  --password secretpass \
  --email user@example.com \
  --config /etc/gitea/app.ini"

Organizations

  1. Click + icon → New Organization
  2. Fill in organization details
  3. Add members and set permissions
  4. Create repos under organization

Backup & Restore

Backup

# SSH to Gitea VM
tfgrid-compose ssh tfgrid-gitea

# Create backup
sudo tar -czf /tmp/gitea-backup-$(date +%Y%m%d).tar.gz \
  /var/lib/gitea/data \
  /etc/gitea

# Download backup
exit
scp root@<gitea-ip>:/tmp/gitea-backup-*.tar.gz ./

Restore

# Upload backup to new VM
scp gitea-backup-*.tar.gz root@<new-gitea-ip>:/tmp/

# SSH to new VM
tfgrid-compose ssh tfgrid-gitea

# Stop service
sudo systemctl stop gitea

# Restore
sudo tar -xzf /tmp/gitea-backup-*.tar.gz -C /

# Fix permissions
sudo chown -R git:git /var/lib/gitea
sudo chown -R git:git /etc/gitea

# Start service
sudo systemctl start gitea

Troubleshooting

Service Not Starting

# Check service status
systemctl status gitea

# View logs
journalctl -u gitea -f

# Check configuration
sudo -u git /usr/local/bin/gitea doctor --config /etc/gitea/app.ini

# Restart service
systemctl restart gitea

Can't Access Web Interface

# Check if port is listening
netstat -tuln | grep 3000

# Test local connection
curl http://localhost:3000

# Check firewall (if using standalone)
ufw status
ufw allow 3000/tcp

Database Issues

# Check database file
ls -lh /var/lib/gitea/data/gitea.db

# Check permissions
ls -ld /var/lib/gitea/data
# Should be owned by git:git

# Repair if needed
sudo -u git sqlite3 /var/lib/gitea/data/gitea.db "PRAGMA integrity_check;"

Performance Issues

For large repositories:

  1. Increase resources in tfgrid-compose.yaml: 

    resources:
  cpu: 4
  memory: 8192
  disk: 100

  2. Redeploy: 

    tfgrid-compose down tfgrid-gitea
tfgrid-compose up tfgrid-gitea

Security Best Practices

Essential Security Steps

  1. Change default password immediately
  2. Enable 2FA (Settings → Security → Two-Factor Authentication)
  3. Use strong passwords for all accounts
  4. Disable registration if not needed (app.ini: DISABLE_REGISTRATION = true)
  5. Regular backups of /var/lib/gitea/data
  6. Keep updated - monitor Gitea releases

SSL/TLS

Always deploy behind a gateway with SSL in production:

tfgrid-compose up tfgrid-gitea --pattern gateway --domain example.com

This provides: - ✅ Free Let's Encrypt SSL certificates - ✅ Automatic HTTPS redirect - ✅ Certificate auto-renewal

Advanced Usage

Webhooks

Configure webhooks to trigger actions on push:

  1. Repository → Settings → Webhooks
  2. Add Webhook
  3. Set URL (e.g., https://example.com/deploy-hook)
  4. Select events (push, pull request, etc.)
  5. Save

Use case: Auto-deploy to gateway when AI agent pushes code.

Git LFS

For large files (>100MB):

# Install git-lfs on client
git lfs install

# Track large files
git lfs track "*.psd"
git lfs track "*.zip"

# Commit and push as normal
git add .
git commit -m "Add large files"
git push

Mirror Repositories

Mirror external repos to Gitea:

  1. New Migration → GitHub/GitLab/etc.
  2. Enter source URL
  3. Configure mirror settings
  4. Gitea will sync automatically

Next Steps

Support

  • TFGrid Docs: https://docs.tfgrid.studio
  • Gitea Docs: https://docs.gitea.com
  • GitHub Issues: https://github.com/tfgrid-studio/tfgrid-gitea/issues
  • Discussions: https://github.com/orgs/tfgrid-studio/discussions

Made with ðŸ”Ĩ for decentralized development

TFGrid Studio Ecosystem

Integrated tools and resources