diff --git a/.github/assets/configuration.png b/.github/assets/configuration.png index ff6feaa..38ddbe7 100644 Binary files a/.github/assets/configuration.png and b/.github/assets/configuration.png differ diff --git a/README.md b/README.md index 0021160..d6ce492 100644 --- a/README.md +++ b/README.md @@ -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://:4321` The application includes a health check endpoint at `/api/health` for monitoring. diff --git a/scripts/README-lxc.md b/scripts/README-lxc.md index d9d73b5..f362e35 100644 --- a/scripts/README-lxc.md +++ b/scripts/README-lxc.md @@ -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://: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) diff --git a/src/pages/docs/architecture.astro b/src/pages/docs/architecture.astro index fda4caf..be28c46 100644 --- a/src/pages/docs/architecture.astro +++ b/src/pages/docs/architecture.astro @@ -41,11 +41,12 @@ import MainLayout from '../../layouts/main.astro';

Technology Stack

{[ - { 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 => (
@@ -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 => (
▸ @@ -288,7 +293,7 @@ import MainLayout from '../../layouts/main.astro';
{[ { 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 => (
@@ -322,7 +327,7 @@ import MainLayout from '../../layouts/main.astro';
-

Note: LXC deployment includes a community script by Tobias/CrazyWolf13

+

Note: LXC deployment is available through the Proxmox VE Community Scripts project.

diff --git a/src/pages/docs/configuration.astro b/src/pages/docs/configuration.astro index ae35fbf..081eae5 100644 --- a/src/pages/docs/configuration.astro +++ b/src/pages/docs/configuration.astro @@ -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 = [

Required Permissions

-

Your GitHub token needs the following permissions:

+

You need to create a Classic GitHub PAT Token with the following scopes:

  • • @@ -204,13 +204,10 @@ const giteaOptions = [
  • • - read:org - Read organization membership -
    • -
  • - • - read:user - Read user profile data + admin:org - Full control of orgs and teams, read and write org projects
+

The organization access is required for mirroring organization repositories.

@@ -301,43 +298,14 @@ const giteaOptions = [

Advanced Configuration

- -
-

Repository Filtering

- -
-

You can include or exclude specific repositories using patterns:

- -
-
-

Include Patterns

-

Only repositories matching these patterns will be mirrored

-
- -
-

Exclude Patterns

-

Repositories matching these patterns will be skipped

-
-
- -
-
Example Patterns
-
    -
  • * - All repositories
    • -
  • org-name/* - All repositories in a specific organization
    • -
  • username/repo-name - A specific repository
    • -
-
-
-

Database Management

Gitea Mirror includes several database management tools that can be run from the command line:

-
- 
{`# Initialize the database (only if it doesn't exist)
+          

+            
{`# Initialize the database (only if it doesn't exist)
 bun run init-db
 
 # Check database status
@@ -357,16 +325,8 @@ bun run cleanup-db`}

         
         

           
Event Management

-          
Events in Gitea Mirror (such as repository mirroring operations) are stored in the SQLite database. You can manage these events using the following scripts:

+          
Events in Gitea Mirror (such as repository mirroring operations) are stored in the SQLite database and can be viewed in the Activity Log page.

           
-          

-            
{`# View all events in the database
-bun scripts/check-events.ts
-
-# Mark all events as read
-bun scripts/mark-events-read.ts`}

-          

-
           

             

               

@@ -375,12 +335,74 @@ 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.

+

Event Management Features:

+
    +
  • + • + View all events with filtering by type, status, and search +
    • +
  • + • + Real-time updates via Server-Sent Events (SSE) +
    • +
  • + • + Clean up old events using the cleanup button in the Activity Log +
    • +
  • + • + Automatic cleanup with configurable retention period +
    • +
+ +
+

Automatic Recovery System

+

Gitea Mirror includes a robust recovery system that automatically handles interrupted operations:

+ +
+
    +
  • + ✓ +
    + Startup Recovery: +

    Automatically recovers interrupted jobs when the application starts

    +
    +
    • +
  • + ✓ +
    + Graceful Shutdown: +

    Saves job state before shutting down to enable recovery on restart

    +
    +
    • +
  • + ✓ +
    + Job State Persistence: +

    Stores mirror job progress in the database for resilience

    +
    +
    • +
+ +
+

Manual recovery tools:

+ 
{`# Run startup recovery manually
+bun run startup-recovery
+
+# Fix interrupted jobs
+bun scripts/fix-interrupted-jobs.ts
+
+# Test recovery system
+bun run test-recovery`}
+
+
+
+

Health Check Endpoint

@@ -408,8 +430,8 @@ bun scripts/mark-events-read.ts`} -
- 
{`# Basic check (returns 200 OK if healthy)
+            

+              
{`# Basic check (returns 200 OK if healthy)
 curl -I http://your-server:port/api/health
 
 # Detailed health information (JSON)
diff --git a/src/pages/docs/quickstart.astro b/src/pages/docs/quickstart.astro
index 1122195..78f021b 100644
--- a/src/pages/docs/quickstart.astro
+++ b/src/pages/docs/quickstart.astro
@@ -178,72 +178,53 @@ bun run start

         
         

           

-            📦 Using LXC Containers (Recommended for server deployments)
+            📦 Using LXC Containers (Recommended for Proxmox VE)
           

           
           

-            

-              

-                

-                  Proxmox VE
-                  (Online Installation)
-                

-                
-                
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:

-                  
    
-                    
  • • Creates a privileged LXC container
    • 
-                    
  • • Installs Bun and dependencies
    • 
-                    
  • • Clones and builds the application
    • 
-                    
  • • Sets up a systemd service
    • 
-                  

-                

+            

+              

+                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)"

               

               
-              

-                

-                  Local LXD
-                  (Offline-friendly)
-                

-                
-                
For testing or environments without internet access:

-                
-                
    
-                  
  1. 
-                    1. Clone the repository locally:
-                    
    
-                      
    git clone https://github.com/arunavo4/gitea-mirror.git
    
-                    
    
-                  
    2. 
-                  
  2. 
-                    2. Download Bun installer:
-                    
    
-                      
    curl -L -o /tmp/bun-linux-x64.zip \
-  https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64.zip
    
-                    
    
-                  
    3. 
-                  
  3. 
-                    3. Run local LXC installer:
-                    
    
-                      
    sudo LOCAL_REPO_DIR=~/path/to/gitea-mirror \
-  ./gitea-mirror/scripts/gitea-mirror-lxc-local.sh
    
-                    
    
-                  
    4. 
-                

+              

+                
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 details, see the LXC Container Deployment Guide.

+              

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