# Gitea Setup on TrueNAS Scale

## Installation Options

### 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)
   ```yaml
   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:
```bash
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:
  ```bash
  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`:
```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

```bash
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)

---

## Next Steps

- [ ] Choose installation method (TrueNAS App vs Custom Docker)
- [ ] Create storage dataset for Gitea data
- [ ] Install Gitea
- [ ] Complete initial setup wizard
- [ ] Create admin account
- [ ] Configure SSH access
- [ ] Set up backup strategy
- [ ] Migrate existing repositories
- [ ] (Optional) Set up HTTPS with reverse proxy
- [ ] (Optional) Configure external access via VPN or port forwarding