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

Gitea Mirror Quick Start Guide

This guide will help you get Gitea Mirror up and running quickly.

Prerequisites

Before you begin, make sure you have:

1
A GitHub account with a personal access token

Create one at GitHub Settings

2
A Gitea instance with an access token

Available in your Gitea Settings > Applications

3
One of the following:
  • Docker and docker-compose (for Docker deployment)
  • Bun 1.2.9+ (for native deployment)
  • Proxmox VE or LXD (for LXC container deployment)

Installation Options

Choose the installation method that works best for your environment.

🐳 Using Docker (Recommended for most users)

Docker provides the easiest way to get started with minimal configuration.

{[ { step: 'Clone the repository', cmd: 'git clone https://github.com/arunavo4/gitea-mirror.git\ncd gitea-mirror' }, { step: 'Start the application in production mode', cmd: 'docker compose up -d' }, { step: 'Access the application', cmd: null, text: 'Open your browser and navigate to http://localhost:4321' } ].map((item, i) => (
STEP {i + 1} {item.step}
{item.cmd ? (
{item.cmd}
) : (

)}
))}

🏃 Using Bun (Native Installation)

If you prefer to run the application directly on your system:

STEP 1 Clone the repository
git clone https://github.com/arunavo4/gitea-mirror.git
cd gitea-mirror
STEP 2 Run the quick setup script
bun run setup

This installs dependencies and initializes the database.

STEP 3 Choose how to run the application
Development Mode
bun run dev

For Bun-specific features, use: bunx --bun astro dev

Production Mode
bun run build
bun run start
STEP 4 Access the application

Open your browser and navigate to http://localhost:4321

📦 Using LXC Containers (Recommended for Proxmox VE)

Proxmox VE Installation (Community Script)

Deploy Gitea Mirror on Proxmox VE using the community-maintained script:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/gitea-mirror.sh)"

This script will:

  • Create a privileged Alpine Linux LXC container
  • Install Bun runtime and dependencies
  • Clone and build Gitea Mirror
  • Configure systemd service for automatic startup
  • Set up the application to run on port 4321

Note

After installation, access Gitea Mirror at http://<container-ip>:4321

For more information about the community script, visit the Community Scripts documentation.

Initial Configuration

Follow these steps to configure Gitea Mirror for first use:

{[ { num: '1', title: 'Create Admin Account', items: [ "You'll be prompted on first access", 'Choose a secure username and password', 'This will be your administrator account' ] }, { num: '2', title: 'Configure GitHub Connection', items: [ 'Navigate to the Configuration page', 'Enter your GitHub credentials', 'Select repositories to mirror', 'Configure filtering options' ] }, { num: '3', title: 'Configure Gitea Connection', items: [ 'Enter your Gitea server URL', 'Enter your Gitea access token', 'Configure organization settings', 'Set default visibility' ] }, { num: '4', title: 'Set Up Scheduling', items: [ 'Enable automatic mirroring', 'Set the mirroring interval', 'Save your configuration' ] } ].map(step => (
{step.num}

{step.title}

    {step.items.map(item => (
  • • {item}
  • ))}
))}

Performing Your First Mirror

After completing the configuration, you can start mirroring repositories:

    {[ 'Click "Import GitHub Data" to fetch repositories from GitHub', 'Go to the Repositories page to view your imported repositories', 'Select the repositories you want to mirror', 'Click "Mirror Selected" to start the mirroring process', 'Monitor the progress on the Activity page', "You'll receive toast notifications about the success or failure of operations" ].map((step, i) => (
  1. {i + 1}
  2. ))}

Troubleshooting

If you encounter any issues:

Check the Activity Log for detailed error messages
Verify your GitHub and Gitea tokens have the correct permissions
Ensure your Gitea instance is accessible from the machine running Gitea Mirror
Check logs based on your deployment method:
Docker: docker logs gitea-mirror
Native: Check terminal output or system logs
LXC: systemctl status gitea-mirror or journalctl -u gitea-mirror -f
Use the health check endpoint: curl http://your-server:4321/api/health
For database issues: bun run check-db or bun run fix-db

Next Steps

After your initial setup:

{[ 'Explore the dashboard for an overview of your mirroring status', 'Set up automatic mirroring schedules for hands-off operation', 'Configure organization mirroring for team repositories', 'Use the cleanup button in Activity Log to manage old events' ].map(item => (
{item}
))}
📖 Check out the Configuration Guide for advanced settings
🏗️ Review the Architecture Documentation to understand the system
📊 For server deployments, set up monitoring using the health check endpoint