Obsidian-Vault/Personal/Areas/Servers/TrueNAS/Quick Reference.md

created, updated

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

TrueNAS Quick Reference

Current Status

✅ All services operational:

• Traefik (reverse proxy with SSL)
• Gitea (git service)
• Servarr stack (media automation)

---

Common Commands

Docker Management

# View running containers
docker ps

# View all containers (including stopped)
docker ps -a

# View logs
docker logs gitea -f          # Follow logs
docker logs traefik --tail 50 # Last 50 lines

# Restart containers
docker restart gitea
docker restart traefik

# Stop/Start with docker-compose
cd /mnt/tank/stacks/gitea
docker compose down
docker compose up -d

# Update containers
docker compose pull
docker compose up -d

# Remove unused images
docker image prune -a

TrueNAS Storage

# Check pool status
zpool status

# List datasets
zfs list

# Create snapshot
zfs snapshot [pool]/docker/gitea@$(date +%Y%m%d)

# List snapshots
zfs list -t snapshot

# Restore from snapshot
zfs rollback [pool]/docker/gitea@20250125

Network Troubleshooting

# Check open ports
netstat -tulpn | grep LISTEN

# Test external connectivity
curl -I https://git.yourdomain.com

# Test DNS
nslookup git.yourdomain.com

# Test port forwarding
nc -zv git.yourdomain.com 2222

# Check public IP
curl ifconfig.me

Gitea Specific

# Enter Gitea container
docker exec -it gitea sh

# Gitea CLI commands (inside container)
gitea admin user list
gitea admin user create --username newuser --email user@example.com --password changeme
gitea dump  # Create backup

# View Gitea config
docker exec gitea cat /data/gitea/conf/app.ini

Traefik Specific

# View Traefik config
docker exec traefik cat /traefik.yml

# Check certificate
docker exec traefik ls -la /letsencrypt

# Restart Traefik to reload config
docker restart traefik

---

File Locations

On TrueNAS Host

/mnt/tank/stacks/
├── traefik/
│   ├── docker-compose.yml
│   ├── traefik.yml
│   └── letsencrypt/
│       └── acme.json
├── gitea/
│   ├── docker-compose.yml
│   └── data/
│       ├── git/
│       │   └── repositories/
│       ├── gitea/
│       │   └── conf/
│       │       └── app.ini
│       └── gitea.db
└── servarr/
    └── docker-compose.yml

Important Config Files

• Traefik config: /mnt/tank/stacks/traefik/traefik.yml
• Gitea config: /mnt/tank/stacks/gitea/data/gitea/conf/app.ini
• Gitea repos: /mnt/tank/stacks/gitea/data/git/repositories/
• SSL certs: /mnt/tank/stacks/traefik/letsencrypt/acme.json

---

Quick Checks

Is Everything Running?

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

Expected output:

NAMES     STATUS          PORTS
gitea     Up 2 days       0.0.0.0:2222->22/tcp, 3000/tcp
traefik   Up 2 days       0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp

Check Certificate Expiry

echo | openssl s_client -servername git.yourdomain.com -connect git.yourdomain.com:443 2>/dev/null | openssl x509 -noout -dates

Disk Usage

# Docker disk usage
docker system df

# Dataset usage
zfs list | grep docker

---

Backup Commands

Quick Gitea Backup

# Create backup
docker exec gitea gitea dump -c /data/gitea/conf/app.ini -f /data/gitea-backup-$(date +%Y%m%d).zip

# Copy backup off server
docker cp gitea:/data/gitea-backup-$(date +%Y%m%d).zip /mnt/tank/backups/

Snapshot Entire Stacks Dataset

# Create snapshot
zfs snapshot tank/stacks@backup-$(date +%Y%m%d)

# Send to backup location
zfs send tank/stacks@backup-$(date +%Y%m%d) | ssh backup-server "zfs recv backup/truenas-stacks"

---

Git Client Setup

SSH Config (~/.ssh/config)

Host git.yourdomain.com
    HostName git.yourdomain.com
    Port 2222
    User git
    IdentityFile ~/.ssh/id_ed25519

Common Git Operations

# Clone via SSH
git clone git@git.yourdomain.com:username/repo.git

# Clone via HTTPS
git clone https://git.yourdomain.com/username/repo.git

# Add remote to existing repo
git remote add origin git@git.yourdomain.com:username/repo.git

# Push
git push -u origin main

# Test SSH connection
ssh -T git@git.yourdomain.com

---

Maintenance Schedule

Weekly

• Check container logs for errors
• Verify backups completed

Monthly

• Update Docker containers
• Check disk usage
• Review Gitea security settings

Quarterly

• Test disaster recovery (restore from backup)
• Review access logs
• Update TrueNAS Scale

---

Emergency Procedures

Container Won't Start

# Check logs
docker logs gitea --tail 100

# Remove and recreate
cd /mnt/tank/stacks/gitea
docker compose down
docker compose up -d

Lost SSL Certificate

# Remove acme.json to force renewal
rm /mnt/tank/stacks/traefik/letsencrypt/acme.json
docker restart traefik

# Wait a few minutes and check
docker logs traefik | grep -i certificate

Corrupted Database

# Stop Gitea
cd /mnt/tank/stacks/gitea
docker compose down

# Restore from snapshot
zfs rollback tank/stacks/gitea@[snapshot-name]

# Or restore from Gitea backup
cd /mnt/tank/stacks/gitea/data
unzip gitea-backup-20250125.zip
# Extract files to appropriate locations

# Restart
docker compose up -d

---

Performance Monitoring

# Container stats
docker stats

# TrueNAS resource usage
top
htop  # If installed

# Check I/O
iostat -x 5

---

Useful URLs

When services are running:

• Gitea: https://git.yourdomain.com
• Traefik Dashboard: https://traefik.yourdomain.com (if configured)
• TrueNAS UI: https://[truenas-ip]

---

Environment Variables Reference

Common environment variables for Gitea:

- GITEA__server__DOMAIN=git.yourdomain.com
- GITEA__server__ROOT_URL=https://git.yourdomain.com
- GITEA__server__SSH_PORT=2222
- GITEA__service__DISABLE_REGISTRATION=true
- GITEA__database__DB_TYPE=sqlite3
- GITEA__repository__ENABLE_PUSH_CREATE_USER=true
- GITEA__security__INSTALL_LOCK=true

See Gitea Config Cheat Sheet for full list.