gitea-mirror/docs/README.md

Gitea Mirror Documentation

Welcome to the Gitea Mirror documentation. This guide covers everything you need to know about developing, building, and deploying the open-source version of Gitea Mirror.

Documentation Overview

Getting Started

• Development Workflow - Set up your development environment and start contributing
• Build Guide - Build Gitea Mirror from source
• Configuration Guide - Configure all available options

Deployment

• Deployment Guide - Deploy to production environments
• Docker Guide - Container-based deployment
• Reverse Proxy Setup - Configure with nginx/Caddy

Features

• SSO/OIDC Setup - Configure authentication providers
• Sponsor Integration - GitHub Sponsors integration
• Webhook Configuration - Set up GitHub webhooks

Marketing Site

• Use Case Library (www/src/pages/use-cases/) - MDX guides surfaced on the landing page use case section
• Use Case Cards (www/src/lib/use-cases.ts) - Central place to update titles, summaries, and CTA links shown across the site

Architecture

• Architecture Overview - System design and components
• API Documentation - REST API endpoints
• Database Schema - SQLite structure

Maintenance

• Migration Guide - Upgrade from previous versions
• Better Auth Migration - Migrate authentication system
• Troubleshooting - Common issues and solutions
• Backup & Restore - Data management

Quick Start

1. Clone and install:

git clone https://github.com/yourusername/gitea-mirror.git
cd gitea-mirror
bun install

2. Configure:

cp .env.example .env
# Edit .env with your GitHub and Gitea tokens

3. Initialize and run:

bun run init-db
bun run dev

4. Access: Open http://localhost:4321

Key Features

• 🔄 Automatic Syncing - Keep repositories synchronized
• 🗂️ Organization Support - Mirror entire organizations
• ⭐ Starred Repos - Mirror your starred repositories
• 🔐 Self-Hosted - Full control over your data
• 🚀 Fast - Built with Bun for optimal performance
• 🔒 Secure - JWT authentication, encrypted tokens

Technology Stack

• Runtime: Bun
• Framework: Astro with React
• Database: SQLite with Drizzle ORM
• Styling: Tailwind CSS v4
• Authentication: Better Auth

System Requirements

• Bun >= 1.2.9
• Node.js >= 20 (optional, for compatibility)
• SQLite 3
• 512MB RAM minimum
• 1GB disk space

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Code of Conduct

Please read our Code of Conduct before contributing.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Wiki: GitHub Wiki

Security

For security issues, please see SECURITY.md.

License

Gitea Mirror is open source software licensed under the MIT License.

---

For detailed information on any topic, please refer to the specific documentation guides listed above.