gitea-mirror/docs/BUILD_GUIDE.md

Build Guide

This guide covers building the open-source version of Gitea Mirror.

Prerequisites

• Bun >= 1.2.9 (primary runtime)
• Node.js >= 20 (for compatibility)
• Git

Quick Start

# Clone repository
git clone https://github.com/yourusername/gitea-mirror.git
cd gitea-mirror

# Install dependencies
bun install

# Initialize database
bun run init-db

# Build for production
bun run build

# Start the application
bun run start

Build Commands

Command	Description
bun run build	Production build
bun run dev	Development server
bun run preview	Preview production build
bun test	Run tests
bun run cleanup-db	Remove database files

Build Output

The build creates:

• dist/ - Production-ready server files
• .astro/ - Build cache (git-ignored)
• data/ - SQLite database location

Development Build

For active development with hot reload:

bun run dev

Access the application at http://localhost:4321

Production Build

# Build
bun run build

# Test the build
bun run preview

# Run in production
bun run start

Docker Build

# Build Docker image
docker build -t gitea-mirror:latest .

# Run container
docker run -p 3000:3000 gitea-mirror:latest

Environment Variables

Create a .env file:

# Database
DATABASE_PATH=./data/gitea-mirror.db

# Authentication
JWT_SECRET=your-secret-here

# GitHub Configuration
GITHUB_TOKEN=ghp_...
GITHUB_WEBHOOK_SECRET=...
GITHUB_EXCLUDED_ORGS=org1,org2,org3  # Optional: Comma-separated list of organizations to exclude from sync

# Gitea Configuration
GITEA_URL=https://your-gitea.com
GITEA_TOKEN=...

Common Build Issues

Missing Dependencies

# Solution
bun install

Database Not Initialized

# Solution
bun run init-db

Port Already in Use

# Change port
PORT=3001 bun run dev

Build Cache Issues

# Clear cache
rm -rf .astro/ dist/
bun run build

Build Optimization

Development Speed

• Use bun run dev for hot reload
• Skip type checking during rapid development
• Keep .astro/ cache between builds

Production Optimization

• Minification enabled automatically
• Tree shaking removes unused code
• Image optimization with Sharp

Validation

After building, verify:

# Check build output
ls -la dist/

# Test server starts
bun run start

# Check health endpoint
curl http://localhost:3000/api/health

CI/CD Build

Example GitHub Actions workflow:

name: Build and Test
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun run build
      - run: bun test

Troubleshooting

Build Fails

1. Check Bun version: bun --version
2. Clear dependencies: rm -rf node_modules && bun install
3. Check for syntax errors: bunx tsc --noEmit

Runtime Errors

1. Check environment variables
2. Verify database exists
3. Check file permissions

Performance

Expected build times:

• Clean build: ~5-10 seconds
• Incremental build: ~2-5 seconds
• Development startup: ~1-2 seconds

Next Steps

• Configure with Configuration Guide
• Deploy with Deployment Guide
• Set up authentication with SSO Guide