TFGrid Gitea Guide¶

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

Overview¶

TFGrid Gitea (v0.1.0) 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.

Status: ✅ Production Ready

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, 4GB RAM
🔐 Secure - Keep your code private on decentralized infrastructure
⚡ Auto-configured - Admin user created automatically during deployment
🌍 Dual Network - Access via WireGuard (private) or Mycelium (P2P)

Quick Deployment¶

Option 1: Standalone Deployment¶

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

# Get access URLs and credentials
tfgrid-compose launch tfgrid-gitea

# Access displayed URLs automatically:
# 🔗 WireGuard:  http://10.1.3.2:3000
# 🔗 Mycelium:   http://[ipv6:address]:3000

What happens during deployment: 1. ✅ VM provisioned on ThreeFold Grid 2. ✅ WireGuard & Mycelium networking configured 3. ✅ Gitea 1.24.6 installed 4. ✅ SQLite database initialized 5. ✅ Admin user gitadmin created automatically 6. ✅ Service started and verified 7. ✅ Environment variables set for easy access

Total deployment time: ~2-3 minutes

Option 2: With Gateway (Recommended)¶

Deploy Gitea behind a gateway for SSL and custom domain:

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

# Select and configure
tfgrid-compose select tfgrid-gitea
tfgrid-compose init
tfgrid-compose launch

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

Option 3: Full AI Dev Stack¶

Deploy AI agent + Gateway + Gitea together:

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

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

Default Credentials¶

Admin user automatically created during deployment:

Username: gitadmin
Password: changeme123
Email: admin@localhost

⚠️ CRITICAL SECURITY: Change the password immediately after first login!

Custom Admin Credentials¶

Set environment variables before deployment:

export GITEA_ADMIN_USER=myadmin
export GITEA_ADMIN_PASSWORD=SecurePass123!
export GITEA_ADMIN_EMAIL=admin@example.com

tfgrid-compose up tfgrid-gitea

Changing Admin Password¶

Via Web Interface: 1. Login to Gitea 2. Click your avatar (top right) → Settings 3. Account → Change Password 4. Enter old password and new password 5. Save changes

Via CLI:

tfgrid-compose ssh tfgrid-gitea
sudo -u gitea /usr/local/bin/gitea admin user change-password \
  --username gitadmin \
  --password YourNewPassword \
  --config /etc/gitea/app.ini

Using with AI Agent¶

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

Enhanced Repository Management¶

Use the new app-specific commands for easy repository management:

# Select Gitea app for shorter commands
tfgrid-compose select tfgrid-gitea

# Create repositories easily
tfgrid-compose create-repo my-website --description "AI-generated website"
tfgrid-compose create-repo api-backend --private --description "Backend API"

# List all repositories
tfgrid-compose list-repos

# Clone repositories
tfgrid-compose clone-repo my-website

# Push code from AI agent
tfgrid-compose push-code my-website /path/to/ai/generated/code

Setup Git Remote (Manual)¶

# SSH to AI agent VM
tfgrid-compose ssh tfgrid-ai-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¶

Login to Gitea
Settings → Applications
Generate New Token
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¶

Automatic Configuration¶

Gitea is pre-configured during deployment with:

✅ SQLite database (no external DB needed)
✅ HTTP server on port 3000
✅ Admin user created automatically
✅ Registration enabled (first user after admin becomes regular user)
✅ ROOT_URL auto-detected from available IPs
✅ Secure secrets generated automatically

Environment Variables¶

TFGrid environment variables are automatically available in Gitea scripts:

# Access from any Gitea script
echo $TFGRID_APP_NAME        # "tfgrid-gitea"
echo $TFGRID_WIREGUARD_IP    # "10.1.3.2"
echo $TFGRID_MYCELIUM_IP     # "ipv6:address"
echo $TFGRID_VM_IP           # Primary IP

Custom Admin User¶

Set before deployment to override defaults:

export GITEA_ADMIN_USER=myadmin
export GITEA_ADMIN_PASSWORD=SecurePass123!
export GITEA_ADMIN_EMAIL=admin@example.com

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 tfgrid-compose commands (Recommended):

# Select Gitea app first
tfgrid-compose select tfgrid-gitea

# Create regular user
tfgrid-compose create-user developer dev@example.com

# Create admin user
tfgrid-compose create-user admin admin@example.com --admin

# List all users
tfgrid-compose list-users

# Reset password
tfgrid-compose reset-password developer

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

Via CLI (Legacy):

# 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¶

Click + icon → New Organization
Fill in organization details
Add members and set permissions
Create repos under organization

Backup & Restore¶

Enhanced Backup Commands¶

# Select Gitea app
tfgrid-compose select tfgrid-gitea

# Create backup with timestamp
tfgrid-compose backup

# Create named backup
tfgrid-compose backup my-backup-2025

# List available backups
tfgrid-compose exec ls -la /opt/gitea/backups/

Manual 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/

# Restore using command
tfgrid-compose restore tfgrid-gitea /tmp/gitea-backup-20251021.tar.gz

# Or manually:
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:

Increase resources in tfgrid-compose.yaml:

resources:
  cpu: 4
  memory: 8192
  disk: 100

Redeploy:

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

Security Best Practices¶

Essential Security Steps¶

Change default password immediately
Enable 2FA (Settings → Security → Two-Factor Authentication)
Use strong passwords for all accounts
Disable registration if not needed (app.ini: DISABLE_REGISTRATION = true)
Regular backups of /var/lib/gitea/data
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:

Repository → Settings → Webhooks
Add Webhook
Set URL (e.g., https://example.com/deploy-hook)
Select events (push, pull request, etc.)
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:

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

App-Specific Commands¶

tfgrid-gitea provides command-line management through tfgrid-compose. Commands defined in the manifest but not all are implemented yet.

Launch & Access (✅ Fully Implemented)¶

# Get access URLs with automatic IP detection
tfgrid-compose launch tfgrid-gitea

# Output shows:
# 🔗 WireGuard:  http://10.1.3.2:3000
# 🔗 Mycelium:   http://[ipv6:addr]:3000
# 🔑 Default login: gitadmin / changeme123

Features: - ✅ Automatically sources TFGrid environment variables - ✅ Detects WireGuard IP from system or environment - ✅ Detects Mycelium IPv6 address - ✅ Falls back to interface detection if vars not set - ✅ Shows default credentials

Status Monitoring (✅ Implemented)¶

# Check deployment status
tfgrid-compose status tfgrid-gitea

# SSH access
tfgrid-compose ssh tfgrid-gitea

# View logs
tfgrid-compose logs tfgrid-gitea

Repository Management (📋 Planned)¶

# Future commands (defined in manifest):
tfgrid-compose create-repo my-project --description "My project"
tfgrid-compose list-repos
tfgrid-compose clone-repo my-project
tfgrid-compose delete-repo old-project --confirm

Status: Command hooks defined, implementation pending

User Management (📋 Planned)¶

# Future commands (defined in manifest):
tfgrid-compose create-user developer dev@example.com
tfgrid-compose list-users
tfgrid-compose reset-password developer

Status: Command hooks defined, implementation pending

Backup & Restore (📋 Planned)¶

# Future commands (defined in manifest):
tfgrid-compose backup tfgrid-gitea
tfgrid-compose restore tfgrid-gitea backup-file.tar.gz

Status: Command hooks defined, implementation pending

Current Workarounds¶

Until commands are implemented, use direct access:

# SSH and use Gitea CLI directly
tfgrid-compose ssh tfgrid-gitea

# Create user
sudo -u gitea /usr/local/bin/gitea admin user create \
  --username newuser \
  --email user@example.com \
  --password userpass \
  --config /etc/gitea/app.ini

# List users
sudo -u gitea /usr/local/bin/gitea admin user list \
  --config /etc/gitea/app.ini

Next Steps¶

AI Agent Guide - Use AI agent with Gitea
Gateway Pattern - Deploy with SSL
App Registry - Explore more apps
Gitea Official Docs - Full Gitea documentation

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

TFGrid Studio

tfgrid.studio

Install

install.tfgrid.studio

Registry

registry.tfgrid.studio

You are here

Documentation

docs.tfgrid.studio