-
- This document provides a comprehensive overview of the Gitea Mirror application architecture, including component diagrams, project structure, and detailed explanations of each part of the system.
-Gitea Mirror is a web application that automates the mirroring of GitHub repositories to Gitea instances. It provides a user-friendly interface for configuring, monitoring, and managing mirroring operations without requiring users to edit configuration files or run Docker commands.
-This guide provides detailed information on how to configure Gitea Mirror for your environment.
-This guide will help you get Gitea Mirror up and running quickly.
-+ This document provides a comprehensive overview of the Gitea Mirror application architecture, including component diagrams, project structure, and detailed explanations of each part of the system. +
++ Gitea Mirror is a web application that automates the mirroring of GitHub repositories to Gitea instances. It provides a user-friendly interface for configuring, monitoring, and managing mirroring operations without requiring users to edit configuration files or run Docker commands. +
+ +{tech.desc}
+{component.tech}
+Repository Data Source
+Mirror Destination
++ The frontend is built with Astro, a modern web framework that allows for server-side rendering and partial hydration. React components are used for interactive elements, providing a responsive and dynamic user interface. +
+ +{component.desc}
++ The backend is built with Bun and provides API endpoints for the frontend to interact with. It handles: +
+ ++ SQLite with Bun's native SQLite driver is used for data persistence, with Drizzle ORM providing type-safe database interactions. The database stores: +
+ +{step.desc}
+{`gitea-mirror/
+├── src/ # Source code
+│ ├── components/ # React components
+│ ├── content/ # Documentation and content
+│ ├── layouts/ # Astro layout components
+│ ├── lib/ # Utility functions and database
+│ ├── pages/ # Astro pages and API routes
+│ └── styles/ # CSS and Tailwind styles
+├── public/ # Static assets
+├── data/ # Database and persistent data
+├── docker/ # Docker configuration
+└── scripts/ # Utility scripts for deployment and maintenance
+ ├── gitea-mirror-lxc-local.sh # Local LXC deployment script
+ └── manage-db.ts # Database management tool`}Gitea Mirror supports multiple deployment options:
+ +{option.desc}
+Note: LXC deployment includes a community script by Tobias/CrazyWolf13
++ This guide provides detailed information on how to configure Gitea Mirror for your environment. +
+Set configuration options through environment variables for automated deployments
+Configure the application through the web interface after installation
+The following environment variables can be used to configure Gitea Mirror:
+ +| Variable | +Description | +Default | +Example | +
|---|---|---|---|
+ {v.name}
+ |
+ {v.desc} | +{v.default} |
+ {v.example} |
+
The application will automatically generate a secure random JWT_SECRET on first run if one isn't provided. This generated secret is stored in the data directory for persistence across container restarts.
While this auto-generation feature provides good security by default, you can still explicitly set your own JWT_SECRET for complete control over your deployment.
After installing and starting Gitea Mirror, you can configure it through the web interface:
+ +http://your-server:port/',
+ 'If this is your first time, you\'ll be guided through creating an admin account',
+ 'Log in with your credentials',
+ 'Go to the Configuration page'
+ ].map((step, i) => (
+ The GitHub configuration section allows you to connect to GitHub and specify which repositories to mirror.
+ +| Option | +Description | +Default | +
|---|---|---|
| {opt.name} | +{opt.desc} | +{opt.default} |
+
Your GitHub token needs the following permissions:
+repo - Full control of private repositories
+ read:org - Read organization membership
+ read:user - Read user profile data
+ The Gitea configuration section allows you to connect to your Gitea instance and specify how repositories should be mirrored.
+ +| Option | +Description | +Default | +
|---|---|---|
| {opt.name} | +{opt.desc} | +{opt.default} |
+
You can configure automatic mirroring on a schedule:
+ +| Option | +Description | +Default | +
|---|---|---|
| Enable Scheduling | +Enable automatic mirroring | +false |
+
| Interval (seconds) | +Time between mirroring operations | +3600 (1 hour) |
+
You can include or exclude specific repositories using patterns:
+ +Only repositories matching these patterns will be mirrored
+Repositories matching these patterns will be skipped
+* - All repositoriesorg-name/* - All repositories in a specific organizationusername/repo-name - A specific repositoryGitea Mirror includes several database management tools that can be run from the command line:
+ +{`# Initialize the database (only if it doesn't exist)
+bun run init-db
+
+# Check database status
+bun run check-db
+
+# Fix database location issues
+bun run fix-db
+
+# Reset all users (for testing signup flow)
+bun run reset-users
+
+# Remove database files completely
+bun run cleanup-db`}Events in Gitea Mirror (such as repository mirroring operations) are stored in the SQLite database. You can manage these events using the following scripts:
+ +{`# View all events in the database
+bun scripts/check-events.ts
+
+# Mark all events as read
+bun scripts/mark-events-read.ts`}For cleaning up old activities and events, use the cleanup button in the Activity Log page of the web interface.
+Gitea Mirror includes a built-in health check endpoint at /api/health that provides:
{`# Basic check (returns 200 OK if healthy)
+curl -I http://your-server:port/api/health
+
+# Detailed health information (JSON)
+curl http://your-server:port/api/health`}Browse guides and technical docs for Gitea Mirror.
{doc.data.description}
- - ))} +{doc.description}
+ + ); + })}+ This guide will help you get Gitea Mirror up and running quickly. +
+Create one at GitHub Settings
+Available in your Gitea Settings > Applications
+Choose the installation method that works best for your environment.
+ + +Docker provides the easiest way to get started with minimal configuration.
+ +{item.cmd}If you prefer to run the application directly on your system:
+ +git clone https://github.com/arunavo4/gitea-mirror.git
+cd gitea-mirrorbun run setupThis installs dependencies and initializes the database.
+bun run devFor Bun-specific features, use: bunx --bun astro dev
bun run build
+bun run startOpen your browser and navigate to http://localhost:4321
+For deploying on a Proxmox VE host with internet access:
+ +# Optional env overrides:
+# CTID HOSTNAME STORAGE DISK_SIZE
+# CORES MEMORY BRIDGE IP_CONF
+sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/arunavo4/gitea-mirror/main/scripts/gitea-mirror-lxc-proxmox.sh)"This script:
+For testing or environments without internet access:
+ +git clone https://github.com/arunavo4/gitea-mirror.gitcurl -L -o /tmp/bun-linux-x64.zip \
+ https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64.zipsudo LOCAL_REPO_DIR=~/path/to/gitea-mirror \
+ ./gitea-mirror/scripts/gitea-mirror-lxc-local.shFor more details, see the LXC Container Deployment Guide.
+Follow these steps to configure Gitea Mirror for first use:
+ +docker logs gitea-mirror
+ systemctl status gitea-mirror
+ or
+ journalctl -u gitea-mirror -f
+ curl http://your-server:4321/api/health
+ bun run check-db or bun run fix-db
+