diff --git a/docs/BETTER_AUTH_MIGRATION.md b/docs/BETTER_AUTH_MIGRATION.md deleted file mode 100644 index 019904f..0000000 --- a/docs/BETTER_AUTH_MIGRATION.md +++ /dev/null @@ -1,175 +0,0 @@ -# Better Auth Migration Guide - -This document describes the migration from the legacy authentication system to Better Auth. - -## Overview - -Gitea Mirror has been migrated to use Better Auth, a modern authentication library that provides: -- Built-in support for email/password authentication -- Session management with secure cookies -- Database adapter with Drizzle ORM -- Ready for OAuth2, OIDC, and SSO integrations -- Type-safe authentication throughout the application - -## Key Changes - -### 1. Database Schema - -New tables added: -- `sessions` - User session management -- `accounts` - Authentication providers (credentials, OAuth, etc.) -- `verification_tokens` - Email verification and password reset tokens - -Modified tables: -- `users` - Added `emailVerified` field - -### 2. Authentication Flow - -**Login:** -- Users now log in with email instead of username -- Endpoint: `/api/auth/sign-in/email` -- Session cookies are automatically managed - -**Registration:** -- Users register with username, email, and password -- Username is stored as an additional field -- Endpoint: `/api/auth/sign-up/email` - -### 3. API Routes - -All auth routes are now handled by Better Auth's catch-all handler: -- `/api/auth/[...all].ts` handles all authentication endpoints - -Legacy routes have been backed up to `/src/pages/api/auth/legacy-backup/` - -### 4. Session Management - -Sessions are now managed by Better Auth: -- Middleware automatically populates `context.locals.user` and `context.locals.session` -- Use `useAuth()` hook in React components for client-side auth -- Sessions expire after 30 days by default - -## Future OIDC/SSO Configuration - -The project is now ready for OIDC and SSO integrations. To enable: - -### 1. Enable SSO Plugin - -```typescript -// src/lib/auth.ts -import { sso } from "better-auth/plugins/sso"; - -export const auth = betterAuth({ - // ... existing config - plugins: [ - sso({ - provisionUser: async (data) => { - // Custom user provisioning logic - return data; - }, - }), - ], -}); -``` - -### 2. Register OIDC Providers - -```typescript -// Example: Register an OIDC provider -await authClient.sso.register({ - issuer: "https://idp.example.com", - domain: "example.com", - clientId: "your-client-id", - clientSecret: "your-client-secret", - providerId: "example-provider", -}); -``` - -### 3. Enable OIDC Provider Mode - -To make Gitea Mirror act as an OIDC provider: - -```typescript -// src/lib/auth.ts -import { oidcProvider } from "better-auth/plugins/oidc"; - -export const auth = betterAuth({ - // ... existing config - plugins: [ - oidcProvider({ - loginPage: "/signin", - consentPage: "/oauth/consent", - metadata: { - issuer: process.env.BETTER_AUTH_URL || "http://localhost:3000", - }, - }), - ], -}); -``` - -### 4. Database Migration for SSO - -When enabling SSO/OIDC, run migrations to add required tables: - -```bash -# Generate the schema -bun drizzle-kit generate - -# Apply the migration -bun drizzle-kit migrate -``` - -New tables that will be added: -- `sso_providers` - SSO provider configurations -- `oauth_applications` - OAuth2 client applications -- `oauth_access_tokens` - OAuth2 access tokens -- `oauth_consents` - User consent records - -## Environment Variables - -Required environment variables: - -```env -# Better Auth configuration -BETTER_AUTH_SECRET=your-secret-key -BETTER_AUTH_URL=http://localhost:3000 - -# Legacy (kept for compatibility) -JWT_SECRET=your-secret-key -``` - -## Migration Script - -To migrate existing users to Better Auth: - -```bash -bun run migrate:better-auth -``` - -This script: -1. Creates credential accounts for existing users -2. Moves password hashes to the accounts table -3. Preserves user creation dates - -## Troubleshooting - -### Login Issues -- Ensure users log in with email, not username -- Check that BETTER_AUTH_SECRET is set -- Verify database migrations have been applied - -### Session Issues -- Clear browser cookies if experiencing session problems -- Check middleware is properly configured -- Ensure auth routes are accessible at `/api/auth/*` - -### Development Tips -- Use `bun db:studio` to inspect database tables -- Check `/api/auth/session` to verify current session -- Enable debug logging in Better Auth for troubleshooting - -## Resources - -- [Better Auth Documentation](https://better-auth.com) -- [Better Auth Astro Integration](https://better-auth.com/docs/integrations/astro) -- [Better Auth Plugins](https://better-auth.com/docs/plugins) \ No newline at end of file diff --git a/docs/BUILD_GUIDE.md b/docs/BUILD_GUIDE.md deleted file mode 100644 index 069f879..0000000 --- a/docs/BUILD_GUIDE.md +++ /dev/null @@ -1,206 +0,0 @@ -# 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=... -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 - -```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) diff --git a/docs/CA_CERTIFICATES.md b/docs/CA_CERTIFICATES.md deleted file mode 120000 index 07e66c1..0000000 --- a/docs/CA_CERTIFICATES.md +++ /dev/null @@ -1 +0,0 @@ -../certs/README.md \ No newline at end of file diff --git a/docs/EXTENDING.md b/docs/EXTENDING.md deleted file mode 100644 index 8affc7d..0000000 --- a/docs/EXTENDING.md +++ /dev/null @@ -1,77 +0,0 @@ -# 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; - cleanup?(): Promise; -} -``` - -## 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/`. \ No newline at end of file diff --git a/docs/SPONSOR_INTEGRATION.md b/docs/SPONSOR_INTEGRATION.md deleted file mode 100644 index 0000566..0000000 --- a/docs/SPONSOR_INTEGRATION.md +++ /dev/null @@ -1,91 +0,0 @@ -# GitHub Sponsors Integration - -This guide shows how GitHub Sponsors is integrated into the open-source version of Gitea Mirror. - -## Components - -### GitHubSponsors Card - -A card component that displays in the sidebar or dashboard: - -```tsx -import { GitHubSponsors } from '@/components/sponsors/GitHubSponsors'; - -// In your layout or dashboard - -``` - -### SponsorButton - -A smaller button for headers or navigation: - -```tsx -import { SponsorButton } from '@/components/sponsors/GitHubSponsors'; - -// In your header - -``` - -## Integration Points - -### 1. Dashboard Sidebar - -Add the sponsor card to the dashboard sidebar for visibility: - -```tsx -// src/components/layout/DashboardLayout.tsx - -``` - -### 2. Header Navigation - -Add the sponsor button to the main navigation: - -```tsx -// src/components/layout/Header.tsx - -``` - -### 3. Settings Page - -Add a support section in settings: - -```tsx -// src/components/settings/SupportSection.tsx - - - Support Development - - - - - -``` - -## Behavior - -- **Only appears in self-hosted mode**: The components automatically hide in hosted mode -- **Non-intrusive**: Designed to be helpful without being annoying -- **Multiple options**: GitHub Sponsors, Buy Me a Coffee, and starring the repo - -## Customization - -You can customize the sponsor components by: - -1. Updating the GitHub Sponsors URL -2. Adding/removing donation platforms -3. Changing the styling to match your theme -4. Adjusting the placement based on user feedback - -## Best Practices - -1. **Don't be pushy**: Show sponsor options tastefully -2. **Provide value first**: Ensure the tool is useful before asking for support -3. **Be transparent**: Explain how sponsorships help the project -4. **Thank sponsors**: Acknowledge supporters in README or releases \ No newline at end of file diff --git a/docs/testing.md b/docs/testing.md deleted file mode 100644 index e3bb12b..0000000 --- a/docs/testing.md +++ /dev/null @@ -1,127 +0,0 @@ -# Testing in Gitea Mirror - -This document provides guidance on testing in the Gitea Mirror project. - -## Current Status - -The project now uses Bun's built-in test runner, which is Jest-compatible and provides a fast, reliable testing experience. We've migrated away from Vitest due to compatibility issues with Bun. - -## Running Tests - -To run tests, use the following commands: - -```bash -# Run all tests -bun test - -# Run tests in watch mode (automatically re-run when files change) -bun test --watch - -# Run tests with coverage reporting -bun test --coverage -``` - -## Test File Naming Conventions - -Bun's test runner automatically discovers test files that match the following patterns: - -- `*.test.{js|jsx|ts|tsx}` -- `*_test.{js|jsx|ts|tsx}` -- `*.spec.{js|jsx|ts|tsx}` -- `*_spec.{js|jsx|ts|tsx}` - -## Writing Tests - -The project uses Bun's test runner with a Jest-compatible API. Here's an example test: - -```typescript -// example.test.ts -import { describe, test, expect } from "bun:test"; - -describe("Example Test", () => { - test("should pass", () => { - expect(true).toBe(true); - }); -}); -``` - -### Testing React Components - -For testing React components, we use React Testing Library: - -```typescript -// component.test.tsx -import { describe, test, expect } from "bun:test"; -import { render, screen } from "@testing-library/react"; -import MyComponent from "../components/MyComponent"; - -describe("MyComponent", () => { - test("renders correctly", () => { - render(); - expect(screen.getByText("Hello World")).toBeInTheDocument(); - }); -}); -``` - -## Test Setup - -The test setup is defined in `src/tests/setup.bun.ts` and includes: - -- Automatic cleanup after each test -- Setup for any global test environment needs - -## Mocking - -Bun's test runner provides built-in mocking capabilities: - -```typescript -import { test, expect, mock } from "bun:test"; - -// Create a mock function -const mockFn = mock(() => "mocked value"); - -test("mock function", () => { - const result = mockFn(); - expect(result).toBe("mocked value"); - expect(mockFn).toHaveBeenCalled(); -}); - -// Mock a module -mock.module("./some-module", () => { - return { - someFunction: () => "mocked module function" - }; -}); -``` - -## CI Integration - -The CI workflow has been updated to use Bun's test runner. Tests are automatically run as part of the CI pipeline. - -## Test Coverage - -To generate test coverage reports, run: - -```bash -bun test --coverage -``` - -This will generate a coverage report in the `coverage` directory. - -## Types of Tests - -The project includes several types of tests: - -1. **Unit Tests**: Testing individual functions and utilities -2. **API Tests**: Testing API endpoints -3. **Component Tests**: Testing React components -4. **Integration Tests**: Testing how components work together - -## Future Improvements - -When expanding the test suite, consider: - -1. Adding more comprehensive API endpoint tests -2. Increasing component test coverage -3. Setting up end-to-end tests with a tool like Playwright -4. Adding performance tests for critical paths