gitea-mirror/src/pages/docs/advanced.astro

---
import MainLayout from '../../layouts/main.astro';
---

<MainLayout title="Advanced Topics - Gitea Mirror">
  <main class="max-w-5xl mx-auto px-4 py-12">
    <div class="sticky top-4 z-10 mb-6">
      <a
        href="/docs/"
        class="inline-flex items-center gap-2 px-3 py-1.5 rounded-md bg-card text-foreground hover:bg-muted transition-colors border border-border focus:ring-2 focus:ring-ring outline-none"
      >
        <span aria-hidden="true">&larr;</span> Back to Documentation
      </a>
    </div>

    <article class="bg-card rounded-2xl shadow-lg p-6 md:p-8 border border-border">
      <!-- Header -->
      <div class="mb-12 space-y-4">
        <div class="flex items-center gap-2 text-sm text-muted-foreground mb-2">
          <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z"/>
            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z"/>
          </svg>
          <span>Advanced</span>
        </div>
        <h1 class="text-4xl font-bold tracking-tight">Advanced Topics</h1>
        <p class="text-lg text-muted-foreground leading-relaxed max-w-4xl">
          Advanced configuration options, deployment strategies, troubleshooting, and performance optimization for Gitea Mirror.
        </p>
      </div>

      <!-- Environment Variables -->
      <section class="mb-12">
        <h2 class="text-2xl font-bold mb-6">Environment Variables</h2>
        
        <p class="text-muted-foreground mb-6">
          Gitea Mirror can be configured using environment variables. These are particularly useful for containerized deployments.
        </p>

        <div class="bg-muted/30 rounded-lg overflow-hidden">
          <table class="w-full text-sm">
            <thead>
              <tr class="border-b border-border">
                <th class="text-left p-3 font-semibold">Variable</th>
                <th class="text-left p-3 font-semibold">Description</th>
                <th class="text-left p-3 font-semibold">Default</th>
              </tr>
            </thead>
            <tbody>
              {[
                { 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) => (
                <tr class={i % 2 === 0 ? 'bg-muted/20' : ''}>
                  <td class="p-3 font-mono text-xs">{item.var}</td>
                  <td class="p-3">{item.desc}</td>
                  <td class="p-3 text-muted-foreground">{item.default}</td>
                </tr>
              ))}
            </tbody>
          </table>
        </div>
      </section>

      <div class="my-12 h-px bg-border/50"></div>

      <!-- Database Management -->
      <section class="mb-12">
        <h2 class="text-2xl font-bold mb-6">Database Management</h2>
        
        <p class="text-muted-foreground mb-6">
          Gitea Mirror uses SQLite for data storage. The database is automatically created on first run.
        </p>

        <h3 class="text-xl font-semibold mb-4">Database Commands</h3>
        
        <div class="space-y-4">
          <div class="bg-card rounded-lg border border-border p-4">
            <h4 class="font-semibold mb-2">Initialize Database</h4>
            <div class="bg-muted/30 rounded p-3 mb-2">
              <code class="text-sm">bun run init-db</code>
            </div>
            <p class="text-sm text-muted-foreground">Creates or recreates the database schema</p>
          </div>

          <div class="bg-card rounded-lg border border-border p-4">
            <h4 class="font-semibold mb-2">Check Database</h4>
            <div class="bg-muted/30 rounded p-3 mb-2">
              <code class="text-sm">bun run check-db</code>
            </div>
            <p class="text-sm text-muted-foreground">Verifies database integrity and displays statistics</p>
          </div>

          <div class="bg-card rounded-lg border border-border p-4">
            <h4 class="font-semibold mb-2">Fix Database</h4>
            <div class="bg-muted/30 rounded p-3 mb-2">
              <code class="text-sm">bun run fix-db</code>
            </div>
            <p class="text-sm text-muted-foreground">Attempts to repair common database issues</p>
          </div>

          <div class="bg-card rounded-lg border border-border p-4">
            <h4 class="font-semibold mb-2">Backup Database</h4>
            <div class="bg-muted/30 rounded p-3 mb-2">
              <code class="text-sm">cp data/gitea-mirror.db data/gitea-mirror.db.backup</code>
            </div>
            <p class="text-sm text-muted-foreground">Always backup before major changes</p>
          </div>
        </div>

        <h3 class="text-xl font-semibold mb-4 mt-8">Database Schema Management</h3>
        
        <div class="bg-blue-500/10 border border-blue-500/20 rounded-lg p-4">
          <div class="flex gap-3">
            <div class="text-blue-600 dark:text-blue-500">
              <svg class="w-5 h-5 mt-0.5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"/>
              </svg>
            </div>
            <div>
              <p class="font-semibold text-blue-600 dark:text-blue-500 mb-1">Drizzle Kit</p>
              <p class="text-sm">Database schema is managed with Drizzle ORM. Use these commands for schema changes:</p>
              <ul class="mt-2 space-y-1 text-sm">
                <li><code class="bg-blue-500/10 px-1 rounded">bun run drizzle-kit generate</code> - Generate migration files</li>
                <li><code class="bg-blue-500/10 px-1 rounded">bun run drizzle-kit push</code> - Apply schema changes directly</li>
                <li><code class="bg-blue-500/10 px-1 rounded">bun run drizzle-kit studio</code> - Open database browser</li>
              </ul>
            </div>
          </div>
        </div>
      </section>

      <div class="my-12 h-px bg-border/50"></div>

      <!-- Performance Optimization -->
      <section class="mb-12">
        <h2 class="text-2xl font-bold mb-6">Performance Optimization</h2>
        
        <h3 class="text-xl font-semibold mb-4">Mirroring Performance</h3>
        
        <div class="grid grid-cols-1 md:grid-cols-2 gap-4 mb-6">
          {[
            {
              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 => (
            <div class="bg-card rounded-lg border border-border p-4">
              <h4 class="font-semibold mb-3">{section.title}</h4>
              <ul class="space-y-1 text-sm text-muted-foreground">
                {section.tips.map(tip => (
                  <li class="flex gap-2">
                    <span>•</span>
                    <span>{tip}</span>
                  </li>
                ))}
              </ul>
            </div>
          ))}
        </div>

        <h3 class="text-xl font-semibold mb-4">Database Performance</h3>
        
        <div class="bg-amber-500/10 border border-amber-500/20 rounded-lg p-4">
          <h4 class="font-semibold text-amber-600 dark:text-amber-500 mb-2">Regular Maintenance</h4>
          <ul class="space-y-1 text-sm">
            <li class="flex gap-2">
              <span class="text-amber-600 dark:text-amber-500">•</span>
              <span>Enable automatic cleanup in Configuration → Automation</span>
            </li>
            <li class="flex gap-2">
              <span class="text-amber-600 dark:text-amber-500">•</span>
              <span>Periodically vacuum the SQLite database: <code class="bg-amber-500/10 px-1 rounded">sqlite3 data/gitea-mirror.db "VACUUM;"</code></span>
            </li>
            <li class="flex gap-2">
              <span class="text-amber-600 dark:text-amber-500">•</span>
              <span>Monitor database size and clean old events regularly</span>
            </li>
          </ul>
        </div>
      </section>

      <div class="my-12 h-px bg-border/50"></div>

      <!-- Reverse Proxy Configuration -->
      <section class="mb-12">
        <h2 class="text-2xl font-bold mb-6">Reverse Proxy Configuration</h2>
        
        <p class="text-muted-foreground mb-6">
          For production deployments, it's recommended to use a reverse proxy like Nginx or Caddy.
        </p>

        <h3 class="text-xl font-semibold mb-4">Nginx Example</h3>
        
        <div class="bg-muted/30 rounded-lg p-4 mb-6">
          <pre class="text-sm overflow-x-auto"><code>{`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;
    }
}`}</code></pre>
        </div>

        <h3 class="text-xl font-semibold mb-4">Caddy Example</h3>
        
        <div class="bg-muted/30 rounded-lg p-4">
          <pre class="text-sm"><code>{`gitea-mirror.example.com {
    reverse_proxy localhost:4321
}`}</code></pre>
        </div>
      </section>

      <div class="my-12 h-px bg-border/50"></div>

      <!-- Monitoring and Health Checks -->
      <section class="mb-12">
        <h2 class="text-2xl font-bold mb-6">Monitoring and Health Checks</h2>
        
        <h3 class="text-xl font-semibold mb-4">Health Check Endpoint</h3>
        
        <div class="bg-card rounded-lg border border-border p-6 mb-6">
          <p class="text-sm text-muted-foreground mb-4">Monitor application health using the built-in endpoint:</p>
          
          <div class="bg-muted/30 rounded p-3 mb-4">
            <code class="text-sm">GET /api/health</code>
          </div>
          
          <p class="text-sm font-semibold mb-2">Response:</p>
          <div class="bg-muted/30 rounded p-3">
            <pre class="text-sm"><code>{`{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00Z",
  "database": "connected",
  "version": "1.0.0"
}`}</code></pre>
          </div>
        </div>

        <h3 class="text-xl font-semibold mb-4">Monitoring with Prometheus</h3>
        
        <p class="text-sm text-muted-foreground mb-4">
          While Gitea Mirror doesn't have built-in Prometheus metrics, you can monitor it using:
        </p>
        
        <ul class="space-y-2 text-sm">
          <li class="flex gap-2">
            <span>•</span>
            <span>Blackbox exporter for endpoint monitoring</span>
          </li>
          <li class="flex gap-2">
            <span>•</span>
            <span>Node exporter for system metrics</span>
          </li>
          <li class="flex gap-2">
            <span>•</span>
            <span>Custom scripts to check database metrics</span>
          </li>
        </ul>
      </section>

      <div class="my-12 h-px bg-border/50"></div>

      <!-- Backup and Recovery -->
      <section class="mb-12">
        <h2 class="text-2xl font-bold mb-6">Backup and Recovery</h2>
        
        <h3 class="text-xl font-semibold mb-4">What to Backup</h3>
        
        <div class="grid grid-cols-1 md:grid-cols-2 gap-4 mb-6">
          <div class="bg-card rounded-lg border border-border p-4">
            <h4 class="font-semibold mb-2">Essential Files</h4>
            <ul class="space-y-1 text-sm text-muted-foreground">
              <li class="font-mono">• data/gitea-mirror.db</li>
              <li class="font-mono">• .env (if using)</li>
              <li class="font-mono">• Custom CA certificates</li>
            </ul>
          </div>
          
          <div class="bg-card rounded-lg border border-border p-4">
            <h4 class="font-semibold mb-2">Optional Files</h4>
            <ul class="space-y-1 text-sm text-muted-foreground">
              <li class="font-mono">• Docker volumes</li>
              <li class="font-mono">• Custom configurations</li>
              <li class="font-mono">• Logs for auditing</li>
            </ul>
          </div>
        </div>

        <h3 class="text-xl font-semibold mb-4">Backup Script Example</h3>
        
        <div class="bg-muted/30 rounded-lg p-4">
          <pre class="text-sm"><code>{`#!/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`}</code></pre>
        </div>
      </section>

      <div class="my-12 h-px bg-border/50"></div>

      <!-- Troubleshooting Guide -->
      <section class="mb-12">
        <h2 class="text-2xl font-bold mb-6">Troubleshooting Guide</h2>
        
        <div class="space-y-4">
          {[
            {
              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 => (
            <div class="bg-card rounded-lg border border-border p-4">
              <h4 class="font-semibold text-amber-600 dark:text-amber-500 mb-2">{item.issue}</h4>
              <ul class="space-y-1 text-sm">
                {item.solutions.map(solution => (
                  <li class="flex gap-2">
                    <span class="text-primary">→</span>
                    <span>{solution}</span>
                  </li>
                ))}
              </ul>
            </div>
          ))}
        </div>
      </section>

      <div class="my-12 h-px bg-border/50"></div>

      <!-- Migration Guide -->
      <section>
        <h2 class="text-2xl font-bold mb-6">Migration Guide</h2>
        
        <h3 class="text-xl font-semibold mb-4">Migrating from JWT to Better Auth</h3>
        
        <div class="bg-gradient-to-r from-primary/5 to-transparent rounded-lg p-6 border-l-4 border-primary">
          <p class="mb-4">If you're upgrading from an older version using JWT authentication:</p>
          
          <ol class="space-y-3 text-sm">
            <li class="flex gap-3">
              <span class="flex-shrink-0 w-6 h-6 bg-primary/10 rounded-full flex items-center justify-center text-xs font-semibold">1</span>
              <div>
                <strong>Backup your database</strong>
                <p class="text-muted-foreground">Always create a backup before migration</p>
              </div>
            </li>
            <li class="flex gap-3">
              <span class="flex-shrink-0 w-6 h-6 bg-primary/10 rounded-full flex items-center justify-center text-xs font-semibold">2</span>
              <div>
                <strong>Update environment variables</strong>
                <p class="text-muted-foreground">Replace JWT_SECRET with BETTER_AUTH_SECRET</p>
              </div>
            </li>
            <li class="flex gap-3">
              <span class="flex-shrink-0 w-6 h-6 bg-primary/10 rounded-full flex items-center justify-center text-xs font-semibold">3</span>
              <div>
                <strong>Run database migrations</strong>
                <p class="text-muted-foreground">New auth tables will be created automatically</p>
              </div>
            </li>
            <li class="flex gap-3">
              <span class="flex-shrink-0 w-6 h-6 bg-primary/10 rounded-full flex items-center justify-center text-xs font-semibold">4</span>
              <div>
                <strong>Users will need to log in again</strong>
                <p class="text-muted-foreground">Previous sessions will be invalidated</p>
              </div>
            </li>
          </ol>
        </div>
      </section>
    </article>
  </main>
</MainLayout>