Advanced

Advanced Topics

Advanced configuration options, deployment strategies, troubleshooting, and performance optimization for Gitea Mirror.

Environment Variables

Gitea Mirror can be configured using environment variables. These are particularly useful for containerized deployments.

{[ { var: 'NODE_ENV', desc: 'Application environment', default: 'production' }, { var: 'PORT', desc: 'Server port', default: '4321' }, { var: 'HOST', desc: 'Server host', default: '0.0.0.0' }, { var: 'BETTER_AUTH_SECRET', desc: 'Authentication secret key', default: 'Auto-generated' }, { var: 'BETTER_AUTH_URL', desc: 'Authentication base URL', default: 'http://localhost:4321' }, { var: 'NODE_EXTRA_CA_CERTS', desc: 'Path to CA certificate file', default: 'None' }, { var: 'DATABASE_URL', desc: 'SQLite database path', default: './data/gitea-mirror.db' }, ].map((item, i) => ( ))}

Variable	Description	Default
{item.var}	{item.desc}	{item.default}

Database Management

Gitea Mirror uses SQLite for data storage. The database is automatically created on first run.

Database Commands

Initialize Database

bun run init-db

Creates or recreates the database schema

Check Database

bun run check-db

Verifies database integrity and displays statistics

Fix Database

bun run fix-db

Attempts to repair common database issues

Backup Database

cp data/gitea-mirror.db data/gitea-mirror.db.backup

Always backup before major changes

Database Schema Management

Drizzle Kit

Database schema is managed with Drizzle ORM. Use these commands for schema changes:

bun run drizzle-kit generate - Generate migration files
bun run drizzle-kit push - Apply schema changes directly
bun run drizzle-kit studio - Open database browser

Performance Optimization

Mirroring Performance

{[ { title: 'Batch Operations', tips: [ 'Mirror multiple repositories at once', 'Use organization-level mirroring', 'Schedule mirroring during off-peak hours' ] }, { title: 'Network Optimization', tips: [ 'Use SSH URLs when possible', 'Enable Git LFS only when needed', 'Consider repository size limits' ] } ].map(section => (

{section.title}

• {tip}

))}

Database Performance

Regular Maintenance

• Enable automatic cleanup in Configuration → Automation
• Periodically vacuum the SQLite database: sqlite3 data/gitea-mirror.db "VACUUM;"
• Monitor database size and clean old events regularly

Reverse Proxy Configuration

For production deployments, it's recommended to use a reverse proxy like Nginx or Caddy.

Nginx Example

{`server {
    listen 80;
    server_name gitea-mirror.example.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name gitea-mirror.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:4321;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        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;
    }

    # SSE endpoint needs special handling
    location /api/sse {
        proxy_pass http://localhost:4321;
        proxy_http_version 1.1;
        proxy_set_header Connection '';
        proxy_set_header Cache-Control 'no-cache';
        proxy_set_header X-Accel-Buffering 'no';
        proxy_read_timeout 86400;
    }
}`}

Caddy Example

{`gitea-mirror.example.com {
    reverse_proxy localhost:4321
}`}

Monitoring and Health Checks

Health Check Endpoint

Monitor application health using the built-in endpoint:

GET /api/health

Response:

{`{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00Z",
  "database": "connected",
  "version": "1.0.0"
}`}

Monitoring with Prometheus

While Gitea Mirror doesn't have built-in Prometheus metrics, you can monitor it using:

• Blackbox exporter for endpoint monitoring
• Node exporter for system metrics
• Custom scripts to check database metrics

Backup and Recovery

What to Backup

Essential Files

• data/gitea-mirror.db
• .env (if using)
• Custom CA certificates

Optional Files

• Docker volumes
• Custom configurations
• Logs for auditing

Backup Script Example

{`#!/bin/bash
BACKUP_DIR="/backups/gitea-mirror"
DATE=$(date +%Y%m%d_%H%M%S)

# Create backup directory
mkdir -p "$BACKUP_DIR/$DATE"

# Backup database
cp data/gitea-mirror.db "$BACKUP_DIR/$DATE/"

# Backup environment
cp .env "$BACKUP_DIR/$DATE/" 2>/dev/null || true

# Create tarball
tar -czf "$BACKUP_DIR/backup_$DATE.tar.gz" -C "$BACKUP_DIR" "$DATE"

# Clean up
rm -rf "$BACKUP_DIR/$DATE"

# Keep only last 7 backups
ls -t "$BACKUP_DIR"/backup_*.tar.gz | tail -n +8 | xargs rm -f`}

Troubleshooting Guide

{[ { issue: 'Application won\'t start', solutions: [ 'Check port availability: `lsof -i :4321`', 'Verify environment variables are set correctly', 'Check database file permissions', 'Review logs for startup errors' ] }, { issue: 'Authentication failures', solutions: [ 'Ensure BETTER_AUTH_SECRET is set and consistent', 'Check BETTER_AUTH_URL matches your deployment', 'Clear browser cookies and try again', 'Verify database contains user records' ] }, { issue: 'Mirroring failures', solutions: [ 'Test GitHub/Gitea connections individually', 'Verify access tokens have correct permissions', 'Check network connectivity and firewall rules', 'Review Activity Log for detailed error messages' ] }, { issue: 'Performance issues', solutions: [ 'Check database size and run cleanup', 'Monitor system resources (CPU, memory, disk)', 'Reduce concurrent mirroring operations', 'Consider upgrading deployment resources' ] } ].map(item => (

{item.issue}

→ {solution}

))}

Migration Guide

Migrating from JWT to Better Auth

If you're upgrading from an older version using JWT authentication:

1
Backup your database
Always create a backup before migration
2
Update environment variables
Replace JWT_SECRET with BETTER_AUTH_SECRET
3
Run database migrations
New auth tables will be created automatically
4
Users will need to log in again
Previous sessions will be invalidated