Updated Docs and Readme

This commit is contained in:
Arunavo Ray
2025-06-16 00:28:55 +05:30
parent 6e673249dc
commit b1346e8c77
6 changed files with 157 additions and 154 deletions

Binary file not shown.

Before

Width:  |  Height:  |  Size: 945 KiB

After

Width:  |  Height:  |  Size: 891 KiB

View File

@@ -167,36 +167,27 @@ docker compose up -d
See [Docker build documentation](./scripts/README-docker.md) for more details.
##### Using LXC Containers
##### Using LXC Containers (Proxmox VE)
Gitea Mirror offers two deployment options for LXC containers:
**1. Proxmox VE (online, recommended for production)**
For Proxmox VE users, Gitea Mirror can be deployed using the community-maintained script:
```bash
# One-command installation on Proxmox VE
# Uses the community-maintained script by Tobias ([CrazyWolf13](https://github.com/CrazyWolf13))
# at [community-scripts/ProxmoxVE](https://github.com/community-scripts/ProxmoxVE)
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/gitea-mirror.sh)"
```
**2. Local testing (offline-friendly, works on developer laptops)**
This community script:
- Creates a privileged Alpine Linux LXC container
- Installs Bun runtime environment
- Clones and builds Gitea Mirror
- Configures a systemd service for automatic startup
- Sets up the application to run on port 4321
```bash
# Download the script
curl -fsSL https://raw.githubusercontent.com/arunavo4/gitea-mirror/main/scripts/gitea-mirror-lxc-local.sh -o gitea-mirror-lxc-local.sh
chmod +x gitea-mirror-lxc-local.sh
> [!NOTE]
> The script is maintained by the [Community Scripts for Proxmox VE](https://community-scripts.github.io/ProxmoxVE/) project.
> For more information, visit the [Gitea Mirror script documentation](https://community-scripts.github.io/ProxmoxVE/scripts?id=gitea-mirror).
# Run with your local repo directory
sudo LOCAL_REPO_DIR=~/Development/gitea-mirror ./gitea-mirror-lxc-local.sh
```
Both scripts:
- Set up a privileged Ubuntu 22.04 LXC container
- Install Bun runtime environment
- Build the application
- Configure a systemd service
- Start the service automatically
After installation, access Gitea Mirror at `http://<container-ip>:4321`
The application includes a health check endpoint at `/api/health` for monitoring.

View File

@@ -1,43 +1,47 @@
# LXC Container Deployment Guide
## Overview
Run **Gitea Mirror** in an isolated LXC container, either:
Run **Gitea Mirror** in an isolated LXC container:
1. **Online, on a Proxmox VE host** script pulls everything from GitHub
2. **Offline / LAN-only, on a developer laptop** script pushes your local checkout + Bun ZIP
1. **Proxmox VE (Recommended)** Using the community-maintained script
2. **Local Development** Using the local LXC script for testing
---
## 1. Proxmox VE (online, recommended for prod)
## 1. Proxmox VE Installation (Recommended)
### Prerequisites
* Proxmox VE node with the default `vmbr0` bridge
* Root shell on the node
* Ubuntu 22.04 LXC template present (`pveam update && pveam download ...`)
* Proxmox VE host with internet access
* Root shell access on the Proxmox node
### One-command install
```bash
# Community-maintained script for Proxmox VE by Tobias ([CrazyWolf13](https://github.com/CrazyWolf13))
# at [community-scripts/ProxmoxVE](https://github.com/community-scripts/ProxmoxVE)
# Official documentation: https://community-scripts.github.io/ProxmoxVE/scripts?id=gitea-mirror
# Community-maintained script from the Proxmox VE Community Scripts project
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/gitea-mirror.sh)"
```
What it does:
### What the script does:
* Uses the community-maintained script from [Community Scripts for Proxmox VE](https://community-scripts.github.io/ProxmoxVE/)
* Installs dependencies and Bun runtime
* Clones & builds `arunavo4/gitea-mirror`
* Creates a systemd service and starts it
* Sets up a random `JWT_SECRET` for security
* Creates a privileged Alpine Linux LXC container
* Installs Bun runtime environment
* Clones the Gitea Mirror repository
* Builds the application
* Configures a systemd service for automatic startup
* Sets up the application to run on port 4321
* Generates a secure `JWT_SECRET` automatically
Browse to:
### Accessing Gitea Mirror:
```
http://<container-ip>:4321
```
### Additional Information:
* **Script Source**: [Community Scripts for Proxmox VE](https://github.com/community-scripts/ProxmoxVE)
* **Documentation**: [Gitea Mirror Script Documentation](https://community-scripts.github.io/ProxmoxVE/scripts?id=gitea-mirror)
* **Support**: [Community Scripts Discord](https://discord.gg/fiXVvSHnBU)
---
## 2. Local testing (LXD on a workstation, works offline)

View File

@@ -41,11 +41,12 @@ import MainLayout from '../../layouts/main.astro';
<h3 class="text-sm font-semibold text-muted-foreground uppercase tracking-wider mb-3">Technology Stack</h3>
<div class="grid grid-cols-1 md:grid-cols-2 gap-3">
{[
{ name: 'Astro', desc: 'Web framework for the frontend' },
{ name: 'Astro', desc: 'Web framework for Server-Side Rendering (SSR)' },
{ name: 'React', desc: 'Component library for interactive UI elements' },
{ name: 'Tailwind CSS v4', desc: 'Utility-first CSS framework (with Vite plugin)' },
{ name: 'Shadcn UI', desc: 'UI component library built on Tailwind CSS' },
{ name: 'SQLite', desc: 'Database for storing configuration, state, and events' },
{ name: 'Bun', desc: 'Runtime environment for the backend' },
{ name: 'Bun', desc: 'JavaScript runtime and package manager' },
{ name: 'Drizzle ORM', desc: 'Type-safe ORM for database interactions' }
].map(tech => (
<div class="flex items-start gap-3">
@@ -186,8 +187,12 @@ import MainLayout from '../../layouts/main.astro';
'Authentication and user management',
'GitHub API integration',
'Gitea API integration',
'Mirroring operations',
'Database interactions'
'Mirroring operations and job queue',
'Real-time updates via Server-Sent Events (SSE) at /api/sse/',
'Job recovery system for interrupted operations',
'Graceful shutdown handling',
'Scheduled automatic mirroring',
'Database interactions with Drizzle ORM'
].map(item => (
<div class="flex gap-3">
<span class="text-primary font-mono text-sm">▸</span>
@@ -288,7 +293,7 @@ import MainLayout from '../../layouts/main.astro';
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4 mb-6">
{[
{ icon: '🐳', name: 'Docker', desc: 'Run as a containerized application using Docker and docker-compose' },
{ icon: '📦', name: 'LXC Containers', desc: 'Deploy in Linux Containers on Proxmox VE or local workstations' },
{ icon: '📦', name: 'LXC Containers', desc: 'Deploy in Linux Containers on Proxmox VE using community script' },
{ icon: '🏃', name: 'Native', desc: 'Run directly on the host system using Bun runtime' }
].map(option => (
<div class="bg-card rounded-lg border border-border p-4 hover:border-primary/50 transition-colors">
@@ -322,7 +327,7 @@ import MainLayout from '../../layouts/main.astro';
</div>
<div class="mt-4 text-sm text-muted-foreground">
<p><strong>Note:</strong> LXC deployment includes a community script by <a href="https://github.com/CrazyWolf13" class="text-primary hover:underline">Tobias/CrazyWolf13</a></p>
<p><strong>Note:</strong> LXC deployment is available through the <a href="https://community-scripts.github.io/ProxmoxVE/scripts?id=gitea-mirror" class="text-primary hover:underline">Proxmox VE Community Scripts</a> project.</p>
</div>
</section>
</article>

View File

@@ -11,16 +11,16 @@ const envVars = [
const githubOptions = [
{ name: 'Username', desc: 'Your GitHub username', default: '-' },
{ name: 'Token', desc: 'GitHub personal access token', default: '-' },
{ name: 'Skip Forks', desc: 'Skip forked repositories', default: 'false' },
{ name: 'Token', desc: 'GitHub personal access token (Classic PAT)', default: '-' },
{ name: 'Private Repositories', desc: 'Include private repositories', default: 'false' },
{ name: 'Mirror Starred', desc: 'Mirror repositories you\'ve starred', default: 'false' },
{ name: 'Mirror Issues', desc: 'Mirror issues from GitHub to Gitea', default: 'false' },
{ name: 'Mirror Wiki', desc: 'Mirror wiki pages from GitHub to Gitea', default: 'false' },
{ name: 'Mirror Starred', desc: 'Mirror starred repositories', default: 'false' },
{ name: 'Mirror Organizations', desc: 'Mirror organization repositories', default: 'false' },
{ name: 'Only Mirror Orgs', desc: 'Only mirror organization repositories', default: 'false' },
{ name: 'Preserve Org Structure', desc: 'Maintain organization structure in Gitea', default: 'false' },
{ name: 'Skip Starred Issues', desc: 'Skip mirroring issues for starred repositories', default: 'false' }
{ name: 'Skip Forks', desc: 'Exclude repositories that are forks', default: 'false' },
{ name: 'Skip Starred Issues', desc: 'Skip issues for starred repositories', default: 'false' }
];
const giteaOptions = [
@@ -196,7 +196,7 @@ const giteaOptions = [
</div>
<div>
<h4 class="font-semibold text-blue-600 dark:text-blue-500 mb-2">Required Permissions</h4>
<p class="text-sm mb-3">Your GitHub token needs the following permissions:</p>
<p class="text-sm mb-3">You need to create a <span class="font-semibold">Classic GitHub PAT Token</span> with the following scopes:</p>
<ul class="space-y-1 text-sm">
<li class="flex gap-2">
<span class="text-blue-600 dark:text-blue-500">•</span>
@@ -204,13 +204,10 @@ const giteaOptions = [
</li>
<li class="flex gap-2">
<span class="text-blue-600 dark:text-blue-500">•</span>
<span><code class="bg-blue-500/10 px-1 py-0.5 rounded">read:org</code> - Read organization membership</span>
</li>
<li class="flex gap-2">
<span class="text-blue-600 dark:text-blue-500">•</span>
<span><code class="bg-blue-500/10 px-1 py-0.5 rounded">read:user</code> - Read user profile data</span>
<span><code class="bg-blue-500/10 px-1 py-0.5 rounded">admin:org</code> - Full control of orgs and teams, read and write org projects</span>
</li>
</ul>
<p class="text-sm mt-2">The organization access is required for mirroring organization repositories.</p>
</div>
</div>
</div>
@@ -301,43 +298,14 @@ const giteaOptions = [
<section class="mb-12">
<h2 class="text-2xl font-bold mb-6">Advanced Configuration</h2>
<!-- Repository Filtering -->
<div class="mb-8">
<h3 class="text-xl font-semibold mb-4">Repository Filtering</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">You can include or exclude specific repositories using patterns:</p>
<div class="space-y-4">
<div>
<h4 class="font-semibold mb-2">Include Patterns</h4>
<p class="text-sm text-muted-foreground">Only repositories matching these patterns will be mirrored</p>
</div>
<div>
<h4 class="font-semibold mb-2">Exclude Patterns</h4>
<p class="text-sm text-muted-foreground">Repositories matching these patterns will be skipped</p>
</div>
</div>
<div class="mt-6 bg-muted/30 rounded-lg p-4">
<h5 class="font-semibold mb-2">Example Patterns</h5>
<ul class="space-y-1 text-sm font-mono">
<li><code>*</code> - All repositories</li>
<li><code>org-name/*</code> - All repositories in a specific organization</li>
<li><code>username/repo-name</code> - A specific repository</li>
</ul>
</div>
</div>
</div>
<!-- Database Management -->
<div class="mb-8">
<h3 class="text-xl font-semibold mb-4">Database Management</h3>
<p class="text-muted-foreground mb-4">Gitea Mirror includes several database management tools that can be run from the command line:</p>
<div class="bg-muted/30 rounded-lg p-4">
<pre class="text-sm"><code>{`# Initialize the database (only if it doesn't exist)
<div class="bg-muted/30 rounded-lg p-4 overflow-x-auto">
<pre class="text-sm whitespace-pre-wrap break-all"><code>{`# Initialize the database (only if it doesn't exist)
bun run init-db
# Check database status
@@ -357,16 +325,8 @@ bun run cleanup-db`}</code></pre>
<!-- Event Management -->
<div class="mb-8">
<h3 class="text-xl font-semibold mb-4">Event Management</h3>
<p class="text-muted-foreground mb-4">Events in Gitea Mirror (such as repository mirroring operations) are stored in the SQLite database. You can manage these events using the following scripts:</p>
<p class="text-muted-foreground mb-4">Events in Gitea Mirror (such as repository mirroring operations) are stored in the SQLite database and can be viewed in the Activity Log page.</p>
<div class="bg-muted/30 rounded-lg p-4 mb-4">
<pre class="text-sm"><code>{`# View all events in the database
bun scripts/check-events.ts
# Mark all events as read
bun scripts/mark-events-read.ts`}</code></pre>
</div>
<div class="bg-green-500/10 border border-green-500/20 rounded-lg p-4">
<div class="flex gap-3">
<div class="text-green-600 dark:text-green-500">
@@ -375,12 +335,74 @@ bun scripts/mark-events-read.ts`}</code></pre>
</svg>
</div>
<div>
<p class="text-sm">For cleaning up old activities and events, use the cleanup button in the Activity Log page of the web interface.</p>
<p class="text-sm mb-2">Event Management Features:</p>
<ul class="space-y-1 text-sm">
<li class="flex gap-2">
<span class="text-green-600 dark:text-green-500">•</span>
<span>View all events with filtering by type, status, and search</span>
</li>
<li class="flex gap-2">
<span class="text-green-600 dark:text-green-500">•</span>
<span>Real-time updates via Server-Sent Events (SSE)</span>
</li>
<li class="flex gap-2">
<span class="text-green-600 dark:text-green-500">•</span>
<span>Clean up old events using the cleanup button in the Activity Log</span>
</li>
<li class="flex gap-2">
<span class="text-green-600 dark:text-green-500">•</span>
<span>Automatic cleanup with configurable retention period</span>
</li>
</ul>
</div>
</div>
</div>
</div>
<!-- Automatic Recovery System -->
<div class="mb-8">
<h3 class="text-xl font-semibold mb-4">Automatic Recovery System</h3>
<p class="text-muted-foreground mb-4">Gitea Mirror includes a robust recovery system that automatically handles interrupted operations:</p>
<div class="bg-card rounded-lg border border-border p-6">
<ul class="space-y-3">
<li class="flex gap-2">
<span class="text-primary">✓</span>
<div>
<span class="font-semibold">Startup Recovery:</span>
<p class="text-sm text-muted-foreground mt-1">Automatically recovers interrupted jobs when the application starts</p>
</div>
</li>
<li class="flex gap-2">
<span class="text-primary">✓</span>
<div>
<span class="font-semibold">Graceful Shutdown:</span>
<p class="text-sm text-muted-foreground mt-1">Saves job state before shutting down to enable recovery on restart</p>
</div>
</li>
<li class="flex gap-2">
<span class="text-primary">✓</span>
<div>
<span class="font-semibold">Job State Persistence:</span>
<p class="text-sm text-muted-foreground mt-1">Stores mirror job progress in the database for resilience</p>
</div>
</li>
</ul>
<div class="mt-4 bg-muted/30 rounded-lg p-4 overflow-x-auto">
<p class="text-sm font-medium mb-2">Manual recovery tools:</p>
<pre class="text-sm whitespace-pre-wrap break-all"><code>{`# Run startup recovery manually
bun run startup-recovery
# Fix interrupted jobs
bun scripts/fix-interrupted-jobs.ts
# Test recovery system
bun run test-recovery`}</code></pre>
</div>
</div>
</div>
<!-- Health Check Endpoint -->
<div>
<h3 class="text-xl font-semibold mb-4">Health Check Endpoint</h3>
@@ -408,8 +430,8 @@ bun scripts/mark-events-read.ts`}</code></pre>
</li>
</ul>
<div class="bg-muted/30 rounded-lg p-4">
<pre class="text-sm"><code>{`# Basic check (returns 200 OK if healthy)
<div class="bg-muted/30 rounded-lg p-4 overflow-x-auto">
<pre class="text-sm whitespace-pre-wrap break-all"><code>{`# Basic check (returns 200 OK if healthy)
curl -I http://your-server:port/api/health
# Detailed health information (JSON)

View File

@@ -178,72 +178,53 @@ bun run start</code></pre>
<!-- LXC Installation -->
<div>
<h3 class="text-xl font-semibold mb-4 flex items-center gap-2">
📦 Using LXC Containers <span class="text-sm text-muted-foreground font-normal">(Recommended for server deployments)</span>
📦 Using LXC Containers <span class="text-sm text-muted-foreground font-normal">(Recommended for Proxmox VE)</span>
</h3>
<div class="bg-card rounded-lg border border-border p-6">
<div class="grid grid-cols-1 md:grid-cols-2 gap-6">
<div class="space-y-4">
<h4 class="font-semibold flex items-center gap-2">
<span>Proxmox VE</span>
<span class="text-xs text-muted-foreground font-normal">(Online Installation)</span>
</h4>
<p class="text-sm text-muted-foreground">For deploying on a Proxmox VE host with internet access:</p>
<div class="bg-muted/30 rounded-lg p-4">
<pre class="text-sm"><code># 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)"</code></pre>
</div>
<div class="text-sm text-muted-foreground space-y-1">
<p class="font-medium">This script:</p>
<ul class="space-y-1 pl-4">
<li class="flex gap-2"><span>•</span> Creates a privileged LXC container</li>
<li class="flex gap-2"><span>•</span> Installs Bun and dependencies</li>
<li class="flex gap-2"><span>•</span> Clones and builds the application</li>
<li class="flex gap-2"><span>•</span> Sets up a systemd service</li>
</ul>
</div>
<div class="space-y-4">
<h4 class="font-semibold flex items-center gap-2">
<span>Proxmox VE Installation</span>
<span class="text-xs text-muted-foreground font-normal">(Community Script)</span>
</h4>
<p class="text-sm text-muted-foreground mb-4">Deploy Gitea Mirror on Proxmox VE using the community-maintained script:</p>
<div class="bg-muted/30 rounded-lg p-4 overflow-x-auto">
<pre class="text-sm whitespace-pre-wrap break-all"><code>bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/gitea-mirror.sh)"</code></pre>
</div>
<div class="space-y-4">
<h4 class="font-semibold flex items-center gap-2">
<span>Local LXD</span>
<span class="text-xs text-muted-foreground font-normal">(Offline-friendly)</span>
</h4>
<p class="text-sm text-muted-foreground">For testing or environments without internet access:</p>
<ol class="space-y-3 text-sm">
<li>
<span class="text-muted-foreground">1. Clone the repository locally:</span>
<div class="bg-muted/30 rounded-lg p-3 mt-1">
<pre><code>git clone https://github.com/arunavo4/gitea-mirror.git</code></pre>
</div>
</li>
<li>
<span class="text-muted-foreground">2. Download Bun installer:</span>
<div class="bg-muted/30 rounded-lg p-3 mt-1">
<pre><code>curl -L -o /tmp/bun-linux-x64.zip \
https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64.zip</code></pre>
</div>
</li>
<li>
<span class="text-muted-foreground">3. Run local LXC installer:</span>
<div class="bg-muted/30 rounded-lg p-3 mt-1">
<pre><code>sudo LOCAL_REPO_DIR=~/path/to/gitea-mirror \
./gitea-mirror/scripts/gitea-mirror-lxc-local.sh</code></pre>
</div>
</li>
</ol>
<div class="mt-4 text-sm text-muted-foreground">
<p class="font-medium mb-2">This script will:</p>
<ul class="space-y-1 pl-4">
<li class="flex gap-2"><span>•</span> Create a privileged Alpine Linux LXC container</li>
<li class="flex gap-2"><span>•</span> Install Bun runtime and dependencies</li>
<li class="flex gap-2"><span>•</span> Clone and build Gitea Mirror</li>
<li class="flex gap-2"><span>•</span> Configure systemd service for automatic startup</li>
<li class="flex gap-2"><span>•</span> Set up the application to run on port 4321</li>
</ul>
</div>
<div class="mt-4 p-3 bg-blue-500/10 border border-blue-500/20 rounded-lg">
<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 class="text-sm">
<p class="font-semibold text-blue-600 dark:text-blue-500 mb-1">Note</p>
<p>After installation, access Gitea Mirror at <code class="bg-blue-500/10 px-1 py-0.5 rounded">http://&lt;container-ip&gt;:4321</code></p>
</div>
</div>
</div>
</div>
<div class="mt-4 pt-4 border-t border-border">
<p class="text-sm text-muted-foreground">For more details, see the <a href="https://github.com/arunavo4/gitea-mirror/blob/main/scripts/README-lxc.md" class="text-primary hover:underline">LXC Container Deployment Guide</a>.</p>
<p class="text-sm text-muted-foreground">
For more information about the community script, visit the
<a href="https://community-scripts.github.io/ProxmoxVE/scripts?id=gitea-mirror" class="text-primary hover:underline">Community Scripts documentation</a>.
</p>
</div>
</div>
</div>