Obsidian-Vault/Personal/Areas/Servers/TrueNAS/Gitea Setup.md

created, updated

created	updated
2025-11-02 10:48	2025-11-02 10:48

Gitea Setup on TrueNAS Scale

Installation Status

✅ Gitea is currently installed and working!

• Deployed using Docker with Traefik reverse proxy
• Accessible via HTTPS through Traefik
• SSH access configured for git operations
• All services operational

---

Installation Options (Reference)

Option 1: TrueNAS Scale Apps (Recommended for Beginners)

TrueNAS Scale has a built-in app catalog that includes Gitea.

Steps:

1. Navigate to Apps in TrueNAS Scale web UI
2. Search for "Gitea"
3. Click Install
4. Configure:
   • Application Name: gitea
   • Storage: Create new dataset or use existing
   • Network: Bridge or Host networking
   • Port: 3000 (web UI), 22 (SSH) - adjust if conflicts
5. Click Install and wait for deployment

Pros:

• GUI-based installation
• Automatic updates via TrueNAS
• Integrated with TrueNAS management

Cons:

• Less control over configuration
• May lag behind latest Gitea releases

---

Option 2: Custom Docker Container (More Control)

Using TrueNAS Scale's Docker support for more customization.

Steps:

1. Create Dataset

   Storage → Create Dataset
   Name: gitea_data
   

2. Create docker-compose.yml (or use TrueNAS Apps → Discover)

   version: "3"
   
   services:
     gitea:
       image: gitea/gitea:latest
       container_name: gitea
       environment:
         - USER_UID=568
         - USER_GID=568
         - GITEA__database__DB_TYPE=sqlite3
       restart: unless-stopped
       volumes:
         - /mnt/pool/gitea_data:/data
       ports:
         - "3000:3000"
         - "2222:22"
   

3. Deploy via Portainer or CLI

Pros:

• Full control over versions and configuration
• Easy to backup and migrate
• Can use docker-compose for multi-container setup

Cons:

• More manual setup
• Need to manage updates yourself

---

Option 3: Kubernetes Deployment (Advanced)

TrueNAS Scale runs on Kubernetes, so you can deploy Gitea charts directly.

Only recommended if you're familiar with Kubernetes

---

Initial Configuration

After installation, access Gitea at http://[truenas-ip]:3000

First-Time Setup Wizard

1. Database Settings:

   • SQLite3 (default, easiest for small setups)
   • Or PostgreSQL/MySQL for better performance

2. General Settings:

   • Site Title: "Your Name's Git"
   • Repository Root Path: /data/git/repositories (default)
   • Git LFS Root Path: /data/git/lfs (default)

3. Server and Third-Party Settings:

   • SSH Server Domain: Your TrueNAS IP or hostname
   • SSH Port: 22 (or 2222 if using custom setup)
   • Gitea HTTP Listen Port: 3000
   • Gitea Base URL: http://[your-ip]:3000/

4. Administrator Account:

   • Create your admin user
   • Set secure password

5. Click Install Gitea

---

Post-Installation Configuration

1. SSH Access for Git Operations

If using port 2222 (recommended to avoid conflicts):

Add to your ~/.ssh/config:

Host git.home
    HostName [truenas-ip]
    Port 2222
    User git

Then clone repos with:

git clone git@git.home:username/repo.git

2. HTTPS Access (Optional but Recommended)

Option A: Reverse Proxy (Nginx Proxy Manager)

• Install Nginx Proxy Manager as another app
• Create proxy host pointing to Gitea
• Add SSL certificate (Let's Encrypt)

Option B: Built-in HTTPS

• Configure in Gitea's app.ini
• Requires SSL certificate

3. Configure Backups

Gitea Data Locations:

• Repositories: /data/git/repositories
• Database: /data/gitea.db (if using SQLite)
• Configuration: /data/gitea/conf/app.ini

TrueNAS Backup Strategy:

• Periodic snapshots of gitea_data dataset
• Replication to another location
• Or use Gitea's built-in backup command:

  gitea dump -c /data/gitea/conf/app.ini
  

4. Performance Tuning

With your 16GB RAM, default settings are fine. If you add many users:

Edit app.ini:

[server]
LFS_START_SERVER = true

[cache]
ENABLED = true
ADAPTER = memory
INTERVAL = 60

[indexer]
ISSUE_INDEXER_TYPE = bleve
REPO_INDEXER_ENABLED = true

---

Usage

Creating First Repository

1. Log into Gitea web UI
2. Click + → New Repository
3. Set name, description, visibility
4. Initialize with README if desired
5. Click Create Repository

Pushing Existing Repo

cd /path/to/your/repo
git remote add origin http://[truenas-ip]:3000/username/repo.git
# or git@git.home:username/repo.git for SSH

git push -u origin main

Migrating from GitHub

1. In Gitea: + → New Migration
2. Select GitHub
3. Enter repo URL
4. Optionally: Add GitHub token for private repos
5. Click Migrate Repository

---

Resource Usage Expectations

With your hardware (i7-1065G7, 16GB RAM):

• Gitea idle: ~50-100 MB RAM
• Gitea active usage: ~100-200 MB RAM
• CPU: Minimal (<5% typically)

Plenty of headroom for other services.

---

Troubleshooting

Can't Access Web UI

• Check firewall rules on TrueNAS
• Verify container is running: Apps → Installed
• Check logs in TrueNAS Apps UI

SSH Clone Not Working

• Verify SSH port is correct (22 or 2222)
• Check SSH keys are added in Gitea: Settings → SSH/GPG Keys
• Test SSH: ssh -T git@[truenas-ip] -p [port]

Slow Performance

• Check TrueNAS system resources (CPU, RAM, disk I/O)
• Consider switching from SQLite to PostgreSQL for large repos
• Enable Gitea caching (see Performance Tuning above)

---

Completed Setup Steps

• Choose installation method (Custom Docker with Traefik)
• Create storage dataset for Gitea data
• Install Gitea
• Complete initial setup wizard
• Create admin account
• Configure SSH access
• Set up HTTPS with Traefik reverse proxy
• Configure external access via port forwarding

Optional Next Steps

• Set up automated backup strategy
• Migrate existing repositories from other platforms
• Configure repository mirroring
• Set up webhooks for CI/CD integration
• Configure additional authentication providers (OAuth, LDAP)