diff --git a/src/content/docs/architecture.md b/src/content/docs/architecture.md index 4045f4b..20f5072 100644 --- a/src/content/docs/architecture.md +++ b/src/content/docs/architecture.md @@ -2,7 +2,7 @@ title: "Architecture" description: "Comprehensive overview of the Gitea Mirror application architecture." order: 1 -updatedDate: 2023-10-15 +updatedDate: 2025-05-22 ---
@@ -21,17 +21,18 @@ The application is built using: - Astro: Web framework for the frontend - React: Component library for interactive UI elements - Shadcn UI: UI component library built on Tailwind CSS -- SQLite: Database for storing configuration and state +- SQLite: Database for storing configuration, state, and events - Bun: Runtime environment for the backend +- Drizzle ORM: Type-safe ORM for database interactions ## Architecture Diagram ```mermaid graph TD subgraph "Gitea Mirror" - Frontend["Frontend
(Astro)"] + Frontend["Frontend
(Astro + React)"] Backend["Backend
(Bun)"] - Database["Database
(SQLite)"] + Database["Database
(SQLite + Drizzle)"] Frontend <--> Backend Backend <--> Database @@ -70,14 +71,15 @@ The backend is built with Bun and provides API endpoints for the frontend to int - Mirroring operations - Database interactions -### Database (SQLite) +### Database (SQLite + Drizzle ORM) -SQLite is used for data persistence, storing: +SQLite with Bun's native SQLite driver is used for data persistence, with Drizzle ORM providing type-safe database interactions. The database stores: - User accounts and authentication data - GitHub and Gitea configuration - Repository and organization information - Mirroring job history and status +- Event notifications and their read status ## Data Flow @@ -93,11 +95,30 @@ SQLite is used for data persistence, storing: 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 +├── docker/ # Docker configuration +└── scripts/ # Utility scripts for deployment and maintenance + ├── gitea-mirror-lxc-proxmox.sh # Proxmox LXC deployment script + ├── gitea-mirror-lxc-local.sh # Local LXC deployment script + └── manage-db.ts # Database management tool ``` + +## Deployment Options + +Gitea Mirror supports multiple deployment options: + +1. **Docker**: Run as a containerized application using Docker and docker-compose +2. **LXC Containers**: Deploy in Linux Containers (LXC) on Proxmox VE or local workstations +3. **Native**: Run directly on the host system using Bun runtime + +Each deployment method has its own advantages: + +- **Docker**: Isolation, easy updates, consistent environment +- **LXC**: Lightweight virtualization, better performance than Docker, system-level isolation +- **Native**: Best performance, direct access to system resources diff --git a/src/content/docs/configuration.md b/src/content/docs/configuration.md index ce4c713..459754e 100644 --- a/src/content/docs/configuration.md +++ b/src/content/docs/configuration.md @@ -2,7 +2,7 @@ title: "Configuration" description: "Guide to configuring Gitea Mirror for your environment." order: 2 -updatedDate: 2023-10-15 +updatedDate: 2025-05-22 ---
@@ -24,10 +24,10 @@ The following environment variables can be used to configure Gitea Mirror: | Variable | Description | Default Value | Example | |----------|-------------|---------------|---------| | `NODE_ENV` | Runtime environment (development, production, test) | `development` | `production` | -| `DATABASE_URL` | SQLite database URL | `sqlite://data/gitea-mirror.db` | `sqlite://path/to/your/database.db` | +| `DATABASE_URL` | SQLite database URL | `file:data/gitea-mirror.db` | `file:path/to/your/database.db` | | `JWT_SECRET` | Secret key for JWT authentication | `your-secret-key-change-this-in-production` | `your-secure-random-string` | | `HOST` | Server host | `localhost` | `0.0.0.0` | -| `PORT` | Server port | `3000` | `8080` | +| `PORT` | Server port | `4321` | `8080` | ### Important Security Note @@ -118,3 +118,58 @@ 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: + +```bash +# 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 +``` + +### 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: + +```bash +# View all events in the database +bun scripts/check-events.ts + +# Clean up old events (default: older than 7 days) +bun scripts/cleanup-events.ts + +# Mark all events as read +bun scripts/mark-events-read.ts +``` + +### Health Check Endpoint + +Gitea Mirror includes a built-in health check endpoint at `/api/health` that provides: + +- System status and uptime +- Database connectivity check +- Memory usage statistics +- Environment information + +You can use this endpoint for monitoring your deployment: + +```bash +# 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 +``` diff --git a/src/content/docs/quickstart.md b/src/content/docs/quickstart.md index 2e75493..ddc01ad 100644 --- a/src/content/docs/quickstart.md +++ b/src/content/docs/quickstart.md @@ -2,7 +2,7 @@ title: "Quick Start Guide" description: "Get started with Gitea Mirror quickly." order: 3 -updatedDate: 2023-10-15 +updatedDate: 2025-05-22 ---
@@ -16,13 +16,16 @@ Before you begin, make sure you have: 1. A GitHub account with a personal access token 2. A Gitea instance with an access token -3. Docker and docker-compose (recommended) or Bun 1.2.9+ installed +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) +### Using Docker (Recommended for most users) Docker provides the easiest way to get started with minimal configuration. @@ -39,7 +42,7 @@ Docker provides the easiest way to get started with minimal configuration. 3. Access the application at [http://localhost:4321](http://localhost:4321) -### Manual Installation +### Using Bun (Native Installation) If you prefer to run the application directly on your system: @@ -62,6 +65,11 @@ If you prefer to run the application directly on your system: bun run dev ``` + Note: For Bun-specific features, use: + ```bash + bunx --bun astro dev + ``` + **Production Mode:** ```bash bun run build @@ -70,6 +78,44 @@ If you prefer to run the application directly on your system: 4. Access the application at [http://localhost:4321](http://localhost:4321) +### Using LXC Containers (Recommended for server deployments) + +#### Proxmox VE (Online Installation) + +For deploying on a Proxmox VE host with internet access: + +```bash +# 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 + +#### Local LXD (Offline-friendly Installation) + +For testing on a local workstation or in environments without internet access: + +1. Clone the repository locally: + ```bash + git clone https://github.com/arunavo4/gitea-mirror.git + ``` + +2. Download the Bun installer once: + ```bash + curl -L -o /tmp/bun-linux-x64.zip https://github.com/oven-sh/bun/releases/latest/download/bun-linux-x64.zip + ``` + +3. Run the local LXC installer: + ```bash + sudo LOCAL_REPO_DIR=~/path/to/gitea-mirror ./gitea-mirror/scripts/gitea-mirror-lxc-local.sh + ``` + +For more details on LXC deployment, see the [LXC Container Deployment Guide](https://github.com/arunavo4/gitea-mirror/blob/main/scripts/README-lxc.md). + ## Initial Configuration Follow these steps to configure Gitea Mirror for first use: @@ -116,7 +162,12 @@ 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 -- For Docker installations, check container logs with `docker logs gitea-mirror` +- Check logs based on your deployment method: + - Docker: `docker logs gitea-mirror` + - Native: Check the terminal output or system logs + - LXC: `systemctl status gitea-mirror` or `journalctl -u gitea-mirror -f` +- Use the health check endpoint to verify system status: `curl http://your-server:4321/api/health` +- For database issues, try the database management tools: `bun run check-db` or `bun run fix-db` ## Next Steps @@ -125,3 +176,7 @@ 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 +- Check out the [Configuration Guide](/configuration) for advanced settings +- Review the [Architecture Documentation](/architecture) to understand the system +- For server deployments, set up monitoring using the health check endpoint +- Consider setting up a cron job to clean up old events: `bun scripts/cleanup-events.ts`