Updated docs

2025-12-06 03:26:44 +03:00 · 2025-07-16 22:51:47 +05:30
parent 948250deef
commit d48981a8c4
5 changed files with 937 additions and 0 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,182 @@
+# Contributing to Gitea Mirror
+
+Thank you for your interest in contributing to Gitea Mirror! This document provides guidelines and instructions for contributing to the open-source version of the project.
+
+## 🎯 Project Overview
+
+Gitea Mirror is an open-source, self-hosted solution for mirroring GitHub repositories to Gitea instances. This guide provides everything you need to know about contributing to the project.
+
+## 🚀 Getting Started
+
+1. Fork the repository
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/yourusername/gitea-mirror.git
+   cd gitea-mirror
+   ```
+
+3. Install dependencies:
+   ```bash
+   bun install
+   ```
+
+4. Set up your environment:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your configuration
+   ```
+
+5. Start development:
+   ```bash
+   bun run dev
+   ```
+
+## 🛠 Development Workflow
+
+### Running the Application
+
+```bash
+# Development mode
+bun run dev
+
+# Build for production
+bun run build
+
+# Run tests
+bun test
+```
+
+### Database Management
+
+```bash
+# Initialize database
+bun run init-db
+
+# Reset database
+bun run cleanup-db && bun run init-db
+```
+
+## 📝 Code Guidelines
+
+### General Principles
+
+1. **Keep it Simple**: Gitea Mirror should remain easy to self-host
+2. **Focus on Core Features**: Prioritize repository mirroring and synchronization
+3. **Database**: Use SQLite for simplicity and portability
+4. **Dependencies**: Minimize external dependencies for easier deployment
+
+### Code Style
+
+- Use TypeScript for all new code
+- Follow the existing code formatting (Prettier is configured)
+- Write meaningful commit messages
+- Add tests for new features
+
+### Scope of Contributions
+
+This project focuses on personal/small team use cases. Please keep contributions aligned with:
+- Core mirroring functionality
+- Self-hosted simplicity
+- Minimal external dependencies
+- SQLite as the database
+- Single-instance deployments
+
+## 🐛 Reporting Issues
+
+1. Check existing issues first
+2. Use issue templates when available
+3. Provide clear reproduction steps
+4. Include relevant logs and screenshots
+
+## 🎯 Pull Request Process
+
+1. Create a feature branch:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes following the code guidelines
+
+3. Test your changes:
+   ```bash
+   # Run tests
+   bun test
+   
+   # Build and check
+   bun run build:oss
+   ```
+
+4. Commit your changes:
+   ```bash
+   git commit -m "feat: add new feature"
+   ```
+
+5. Push to your fork and create a Pull Request
+
+### PR Requirements
+
+- Clear description of changes
+- Tests for new functionality
+- Documentation updates if needed
+- No breaking changes without discussion
+- Passes all CI checks
+
+## 🏗 Architecture Overview
+
+```
+src/
+├── components/     # React components
+├── lib/           # Core utilities
+│   ├── db/        # Database queries (SQLite only)
+│   ├── github/    # GitHub API integration
+│   ├── gitea/     # Gitea API integration
+│   └── utils/     # Helper functions
+├── pages/         # Astro pages
+│   └── api/       # API endpoints
+└── types/         # TypeScript types
+```
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+bun test
+
+# Run tests in watch mode
+bun test:watch
+
+# Run with coverage
+bun test:coverage
+```
+
+## 📚 Documentation
+
+- Update README.md for user-facing changes
+- Add JSDoc comments for new functions
+- Update .env.example for new environment variables
+
+## 💡 Feature Requests
+
+We welcome feature requests! When proposing new features, please consider:
+- Does it enhance the core mirroring functionality?
+- Will it benefit self-hosted users?
+- Can it be implemented without complex external dependencies?
+- Does it maintain the project's simplicity?
+
+## 🤝 Community
+
+- Be respectful and constructive
+- Help others in issues and discussions
+- Share your use cases and feedback
+
+## 📄 License
+
+By contributing, you agree that your contributions will be licensed under the same license as the project (MIT).
+
+## Questions?
+
+Feel free to open an issue for any questions about contributing!
+
+---
+
+Thank you for helping make Gitea Mirror better! 🎉
--- a/docs/BUILD_GUIDE.md
+++ b/docs/BUILD_GUIDE.md
@@ -0,0 +1,205 @@
+# 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
+
+```bash
+# 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:
+
+```bash
+bun run dev
+```
+
+Access the application at http://localhost:4321
+
+## Production Build
+
+```bash
+# Build
+bun run build
+
+# Test the build
+bun run preview
+
+# Run in production
+bun run start
+```
+
+## Docker Build
+
+```dockerfile
+# 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:
+
+```env
+# Database
+DATABASE_PATH=./data/gitea-mirror.db
+
+# Authentication
+JWT_SECRET=your-secret-here
+
+# GitHub Configuration
+GITHUB_TOKEN=ghp_...
+GITHUB_WEBHOOK_SECRET=...
+
+# Gitea Configuration
+GITEA_URL=https://your-gitea.com
+GITEA_TOKEN=...
+```
+
+## Common Build Issues
+
+### Missing Dependencies
+
+```bash
+# Solution
+bun install
+```
+
+### Database Not Initialized
+
+```bash
+# Solution
+bun run init-db
+```
+
+### Port Already in Use
+
+```bash
+# Change port
+PORT=3001 bun run dev
+```
+
+### Build Cache Issues
+
+```bash
+# 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:
+
+```bash
+# 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:
+
+```yaml
+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](./CONFIGURATION.md)
+- Deploy with [Deployment Guide](./DEPLOYMENT.md)
+- Set up authentication with [SSO Guide](./SSO-OIDC-SETUP.md)
--- a/docs/DEVELOPMENT_WORKFLOW.md
+++ b/docs/DEVELOPMENT_WORKFLOW.md
@@ -0,0 +1,355 @@
+# Development Workflow
+
+This guide covers the development workflow for the open-source Gitea Mirror.
+
+## Getting Started
+
+### Prerequisites
+
+- Bun >= 1.2.9
+- Node.js >= 20
+- Git
+- GitHub account (for API access)
+- Gitea instance (for testing)
+
+### Initial Setup
+
+1. **Clone the repository**:
+```bash
+git clone https://github.com/yourusername/gitea-mirror.git
+cd gitea-mirror
+```
+
+2. **Install dependencies**:
+```bash
+bun install
+```
+
+3. **Initialize database**:
+```bash
+bun run init-db
+```
+
+4. **Configure environment**:
+```bash
+cp .env.example .env
+# Edit .env with your settings
+```
+
+5. **Start development server**:
+```bash
+bun run dev
+```
+
+## Development Commands
+
+| Command | Description |
+|---------|-------------|
+| `bun run dev` | Start development server with hot reload |
+| `bun run build` | Build for production |
+| `bun run preview` | Preview production build |
+| `bun test` | Run all tests |
+| `bun test:watch` | Run tests in watch mode |
+| `bun run db:studio` | Open database GUI |
+
+## Project Structure
+
+```
+gitea-mirror/
+├── src/
+│   ├── components/      # React components
+│   ├── pages/          # Astro pages & API routes
+│   ├── lib/            # Core logic
+│   │   ├── db/         # Database queries
+│   │   ├── utils/      # Helper functions
+│   │   └── modules/    # Module system
+│   ├── hooks/          # React hooks
+│   └── types/          # TypeScript types
+├── public/             # Static assets
+├── scripts/            # Utility scripts
+└── tests/              # Test files
+```
+
+## Feature Development
+
+### Adding a New Feature
+
+1. **Create feature branch**:
+```bash
+git checkout -b feature/my-feature
+```
+
+2. **Plan your changes**:
+- UI components in `/src/components/`
+- API endpoints in `/src/pages/api/`
+- Database queries in `/src/lib/db/queries/`
+- Types in `/src/types/`
+
+3. **Implement the feature**:
+
+**Example: Adding a new API endpoint**
+```typescript
+// src/pages/api/my-endpoint.ts
+import type { APIRoute } from 'astro';
+import { getUserFromCookie } from '@/lib/auth-utils';
+
+export const GET: APIRoute = async ({ request }) => {
+  const user = await getUserFromCookie(request);
+  if (!user) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+
+  // Your logic here
+  return new Response(JSON.stringify({ data: 'success' }), {
+    headers: { 'Content-Type': 'application/json' }
+  });
+};
+```
+
+4. **Write tests**:
+```typescript
+// src/lib/my-feature.test.ts
+import { describe, it, expect } from 'bun:test';
+
+describe('My Feature', () => {
+  it('should work correctly', () => {
+    expect(myFunction()).toBe('expected');
+  });
+});
+```
+
+5. **Update documentation**:
+- Add JSDoc comments
+- Update README if needed
+- Document API changes
+
+## Database Development
+
+### Schema Changes
+
+1. **Modify schema**:
+```typescript
+// src/lib/db/schema.ts
+export const myTable = sqliteTable('my_table', {
+  id: text('id').primaryKey(),
+  name: text('name').notNull(),
+  createdAt: integer('created_at').notNull(),
+});
+```
+
+2. **Generate migration**:
+```bash
+bun run db:generate
+```
+
+3. **Apply migration**:
+```bash
+bun run db:migrate
+```
+
+### Writing Queries
+
+```typescript
+// src/lib/db/queries/my-queries.ts
+import { db } from '../index';
+import { myTable } from '../schema';
+
+export async function getMyData(userId: string) {
+  return db.select()
+    .from(myTable)
+    .where(eq(myTable.userId, userId));
+}
+```
+
+## Testing
+
+### Unit Tests
+
+```bash
+# Run all tests
+bun test
+
+# Run specific test file
+bun test auth
+
+# Watch mode
+bun test:watch
+
+# Coverage
+bun test:coverage
+```
+
+### Manual Testing Checklist
+
+- [ ] Feature works as expected
+- [ ] No console errors
+- [ ] Responsive on mobile
+- [ ] Handles errors gracefully
+- [ ] Loading states work
+- [ ] Form validation works
+- [ ] API returns correct status codes
+
+## Debugging
+
+### VSCode Configuration
+
+Create `.vscode/launch.json`:
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "bun",
+      "request": "launch", 
+      "name": "Debug Bun",
+      "program": "${workspaceFolder}/src/index.ts",
+      "cwd": "${workspaceFolder}",
+      "env": {
+        "NODE_ENV": "development"
+      }
+    }
+  ]
+}
+```
+
+### Debug Logging
+
+```typescript
+// Development only logging
+if (import.meta.env.DEV) {
+  console.log('[Debug]', data);
+}
+```
+
+## Code Style
+
+### TypeScript
+
+- Use strict mode
+- Define interfaces for all data structures
+- Avoid `any` type
+- Use proper error handling
+
+### React Components
+
+- Use functional components
+- Implement proper loading states
+- Handle errors with error boundaries
+- Use TypeScript for props
+
+### API Routes
+
+- Always validate input
+- Return proper status codes
+- Use consistent error format
+- Document with JSDoc
+
+## Git Workflow
+
+### Commit Messages
+
+Follow conventional commits:
+```
+feat: add repository filtering
+fix: resolve sync timeout issue
+docs: update API documentation
+style: format code with prettier
+refactor: simplify auth logic
+test: add user creation tests
+chore: update dependencies
+```
+
+### Pull Request Process
+
+1. Create feature branch
+2. Make changes
+3. Write/update tests
+4. Update documentation
+5. Create PR with description
+6. Address review feedback
+7. Squash and merge
+
+## Performance
+
+### Development Tips
+
+- Use React DevTools
+- Monitor bundle size
+- Profile database queries
+- Check memory usage
+
+### Optimization
+
+- Lazy load components
+- Optimize images
+- Use database indexes
+- Cache API responses
+
+## Common Issues
+
+### Port Already in Use
+
+```bash
+# Use different port
+PORT=3001 bun run dev
+```
+
+### Database Locked
+
+```bash
+# Reset database
+bun run cleanup-db
+bun run init-db
+```
+
+### Type Errors
+
+```bash
+# Check types
+bunx tsc --noEmit
+```
+
+## Release Process
+
+1. **Update version**:
+```bash
+npm version patch  # or minor/major
+```
+
+2. **Update CHANGELOG.md**
+
+3. **Build and test**:
+```bash
+bun run build
+bun test
+```
+
+4. **Create release**:
+```bash
+git tag v2.23.0
+git push origin v2.23.0
+```
+
+5. **Create GitHub release**
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch
+3. Commit your changes
+4. Push to your fork
+5. Create a Pull Request
+
+## Resources
+
+- [Astro Documentation](https://docs.astro.build)
+- [Bun Documentation](https://bun.sh/docs)
+- [Drizzle ORM](https://orm.drizzle.team)
+- [React Documentation](https://react.dev)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
+
+## Getting Help
+
+- Check existing [issues](https://github.com/yourusername/gitea-mirror/issues)
+- Join [discussions](https://github.com/yourusername/gitea-mirror/discussions)
+- Read the [FAQ](./FAQ.md)
--- a/docs/EXTENDING.md
+++ b/docs/EXTENDING.md
@@ -0,0 +1,77 @@
+# Extending Gitea Mirror
+
+Gitea Mirror is designed with extensibility in mind through a module system.
+
+## Module System
+
+The application provides a module interface that allows extending functionality:
+
+```typescript
+export interface Module {
+  name: string;
+  version: string;
+  init(app: AppContext): Promise<void>;
+  cleanup?(): Promise<void>;
+}
+```
+
+## Creating Custom Modules
+
+You can create custom modules to add features:
+
+```typescript
+// my-module.ts
+export class MyModule implements Module {
+  name = 'my-module';
+  version = '1.0.0';
+
+  async init(app: AppContext) {
+    // Add your functionality
+    app.addRoute('/api/my-endpoint', this.handler);
+  }
+
+  async handler(context) {
+    return new Response('Hello from my module!');
+  }
+}
+```
+
+## Module Context
+
+Modules receive an `AppContext` with:
+- Database access
+- Event system
+- Route registration
+- Configuration
+
+## Private Extensions
+
+If you're developing private extensions:
+
+1. Create a separate package/repository
+2. Implement the module interface
+3. Use Bun's linking feature for development:
+   ```bash
+   # In your extension
+   bun link
+   
+   # In gitea-mirror
+   bun link your-extension
+   ```
+
+## Best Practices
+
+- Keep modules focused on a single feature
+- Use TypeScript for type safety
+- Handle errors gracefully
+- Clean up resources in `cleanup()`
+- Document your module's API
+
+## Community Modules
+
+Share your modules with the community:
+- Create a GitHub repository
+- Tag it with `gitea-mirror-module`
+- Submit a PR to list it in our docs
+
+For more details on the module system, see the source code in `/src/lib/modules/`.
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,118 @@
+# Gitea Mirror Documentation
+
+Welcome to the Gitea Mirror documentation. This guide covers everything you need to know about developing, building, and deploying the open-source version of Gitea Mirror.
+
+## Documentation Overview
+
+### Getting Started
+
+- **[Development Workflow](./DEVELOPMENT_WORKFLOW.md)** - Set up your development environment and start contributing
+- **[Build Guide](./BUILD_GUIDE.md)** - Build Gitea Mirror from source
+- **[Configuration Guide](./CONFIGURATION.md)** - Configure all available options
+
+### Deployment
+
+- **[Deployment Guide](./DEPLOYMENT.md)** - Deploy to production environments
+- **[Docker Guide](./DOCKER.md)** - Container-based deployment
+- **[Reverse Proxy Setup](./REVERSE_PROXY.md)** - Configure with nginx/Caddy
+
+### Features
+
+- **[SSO/OIDC Setup](./SSO-OIDC-SETUP.md)** - Configure authentication providers
+- **[Sponsor Integration](./SPONSOR_INTEGRATION.md)** - GitHub Sponsors integration
+- **[Webhook Configuration](./WEBHOOKS.md)** - Set up GitHub webhooks
+
+### Architecture
+
+- **[Architecture Overview](./ARCHITECTURE.md)** - System design and components
+- **[API Documentation](./API.md)** - REST API endpoints
+- **[Database Schema](./DATABASE.md)** - SQLite structure
+
+### Maintenance
+
+- **[Migration Guide](../MIGRATION_GUIDE.md)** - Upgrade from previous versions
+- **[Better Auth Migration](./BETTER_AUTH_MIGRATION.md)** - Migrate authentication system
+- **[Troubleshooting](./TROUBLESHOOTING.md)** - Common issues and solutions
+- **[Backup & Restore](./BACKUP.md)** - Data management
+
+## Quick Start
+
+1. **Clone and install**:
+```bash
+git clone https://github.com/yourusername/gitea-mirror.git
+cd gitea-mirror
+bun install
+```
+
+2. **Configure**:
+```bash
+cp .env.example .env
+# Edit .env with your GitHub and Gitea tokens
+```
+
+3. **Initialize and run**:
+```bash
+bun run init-db
+bun run dev
+```
+
+4. **Access**: Open http://localhost:4321
+
+## Key Features
+
+- 🔄 **Automatic Mirroring** - Keep repositories synchronized
+- 🗂️ **Organization Support** - Mirror entire organizations
+- ⭐ **Starred Repos** - Mirror your starred repositories
+- 🔐 **Self-Hosted** - Full control over your data
+- 🚀 **Fast** - Built with Bun for optimal performance
+- 🔒 **Secure** - JWT authentication, encrypted tokens
+
+## Technology Stack
+
+- **Runtime**: Bun
+- **Framework**: Astro with React
+- **Database**: SQLite with Drizzle ORM
+- **Styling**: Tailwind CSS v4
+- **Authentication**: Better Auth
+
+## System Requirements
+
+- Bun >= 1.2.9
+- Node.js >= 20 (optional, for compatibility)
+- SQLite 3
+- 512MB RAM minimum
+- 1GB disk space
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](../CONTRIBUTING.md) for details.
+
+### Development Setup
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+### Code of Conduct
+
+Please read our [Code of Conduct](../CODE_OF_CONDUCT.md) before contributing.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/yourusername/gitea-mirror/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/yourusername/gitea-mirror/discussions)
+- **Wiki**: [GitHub Wiki](https://github.com/yourusername/gitea-mirror/wiki)
+
+## Security
+
+For security issues, please see [SECURITY.md](../SECURITY.md).
+
+## License
+
+Gitea Mirror is open source software licensed under the [MIT License](../LICENSE).
+
+---
+
+For detailed information on any topic, please refer to the specific documentation guides listed above.