diff --git a/.codecov.yml b/.codecov.yml new file mode 100644 index 00000000..e7f7311f --- /dev/null +++ b/.codecov.yml @@ -0,0 +1,33 @@ +# Codecov configuration - require 75% overall coverage by default +# Adjust target as needed + +coverage: + status: + project: + default: + target: 75% + threshold: 0% + +# Fail CI if Codecov upload/report indicates a problem +require_ci_to_pass: yes + +# Exclude folders from Codecov +ignore: + - "**/tests/*" + - "**/test/*" + - "**/__tests__/*" + - "**/test_*.go" + - "**/*_test.go" + - "**/*.test.ts" + - "**/*.test.tsx" + - "docs/*" + - ".github/*" + - "scripts/*" + - "tools/*" + - "frontend/node_modules/*" + - "frontend/dist/*" + - "frontend/coverage/*" + - "backend/cmd/seed/*" + - "backend/data/*" + - "backend/coverage/*" + - "*.md" diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 00000000..019c4750 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,76 @@ +# Version control +.git +.gitignore +.github/ + +# Python +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +.venv/ +venv/ +env/ +ENV/ +.pytest_cache/ +.coverage +*.cover +.hypothesis/ +htmlcov/ +*.egg-info/ + +# Node/Frontend build artifacts +frontend/node_modules/ +frontend/coverage/ +frontend/dist/ +frontend/.vite/ +frontend/*.tsbuildinfo + +# Go/Backend +backend/api +backend/*.out +backend/coverage/ +backend/coverage.*.out + +# Databases (runtime) +backend/data/*.db +backend/cmd/api/data/*.db +*.sqlite +*.sqlite3 + +# IDE +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# Logs +*.log +logs/ + +# Environment +.env.local +.env.*.local + +# OS +.DS_Store +Thumbs.db + +# Documentation +docs/ +*.md +!README.md + +# Docker +docker-compose*.yml +**/Dockerfile.* + +# CI/CD +.github/ +.pre-commit-config.yaml + +# Scripts +scripts/ +tools/ diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..fe92692c --- /dev/null +++ b/.gitignore @@ -0,0 +1,70 @@ +# Python +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +.venv/ +venv/ +env/ +ENV/ +.pytest_cache/ +.coverage +*.cover +.hypothesis/ +htmlcov/ + +# Node/Frontend +frontend/node_modules/ +backend/node_modules/ +frontend/dist/ +frontend/coverage/ +frontend/.vite/ +frontend/*.tsbuildinfo + +# Go/Backend +backend/api +backend/*.out +backend/coverage/ +backend/coverage.*.out + +# Databases +*.db +*.sqlite +*.sqlite3 +backend/data/*.db +backend/cmd/api/data/*.db + +# IDE +.vscode/ +.idea/ +*.swp +*.swo +*~ +.DS_Store +*.code-workspace + +# Logs +*.log +logs/ +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# Environment +.env +.env.* +!.env.example + +# OS +Thumbs.db + +# Caddy +backend/data/caddy/ + +# Docker +docker-compose.override.yml + +# Testing +coverage/ +*.xml diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000..a6b59695 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,27 @@ +repos: + - repo: local + hooks: + - id: python-compile + name: python compile check + entry: tools/python_compile_check.sh + language: script + files: ".*\\.py$" + pass_filenames: false + always_run: true + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.6.0 + hooks: + - id: end-of-file-fixer + exclude: '^(frontend/(coverage|dist|node_modules|\.vite)/|.*\.tsbuildinfo$)' + - id: trailing-whitespace + exclude: '^(frontend/(coverage|dist|node_modules|\.vite)/|.*\.tsbuildinfo$)' + - id: check-yaml + - id: check-added-large-files + - repo: local + hooks: + - id: dockerfile-check + name: dockerfile validation + entry: tools/dockerfile_check.sh + language: script + files: "Dockerfile.*" + pass_filenames: true diff --git a/.sourcery.yml b/.sourcery.yml new file mode 100644 index 00000000..628ec063 --- /dev/null +++ b/.sourcery.yml @@ -0,0 +1,4 @@ +version: 1 +exclude: + - frontend/dist/** + - frontend/node_modules/** diff --git a/.version b/.version new file mode 100644 index 00000000..388bb068 --- /dev/null +++ b/.version @@ -0,0 +1 @@ +0.1.0-alpha diff --git a/ARCHITECTURE_PLAN.md b/ARCHITECTURE_PLAN.md new file mode 100644 index 00000000..4801271e --- /dev/null +++ b/ARCHITECTURE_PLAN.md @@ -0,0 +1,49 @@ +# CaddyProxyManager+ Architecture Plan + +## Stack Overview +- **Backend**: Go 1.24, Gin HTTP framework, GORM ORM, SQLite for local/stateful storage. +- **Frontend**: React 18 + TypeScript with Vite, React Query for data fetching, React Router for navigation. +- **API Contract**: REST/JSON over `/api/v1`, versioned to keep room for breaking changes. +- **Deployment**: Container-first via multi-stage Docker build (Node β†’ Go), future compose bundle for Caddy runtime. + +## Backend +- `backend/cmd/api`: Entry point wires configuration, database, and HTTP server lifecycle. +- `internal/config`: Reads environment variables (`CPM_ENV`, `CPM_HTTP_PORT`, `CPM_DB_PATH`). Defaults to `development`, `8080`, `./data/cpm.db` respectively. +- `internal/database`: Wraps GORM + SQLite connection handling and enforces data-directory creation. +- `internal/server`: Creates Gin engine, registers middleware, wires graceful shutdown, and exposes `Run(ctx)` for signal-aware lifecycle. +- `internal/api`: Versioned routing layer. Initial resources: + - `GET /api/v1/health`: Simple status response for readiness checks. + - CRUD `/api/v1/proxy-hosts`: Minimal data model used to validate persistence, shape matches Issue #1 requirements (name, domain, upstream target, toggles). +- `internal/models`: Source of truth for persistent entities. Future migrations will extend `ProxyHost` with SSL, ACL, audit metadata. +- Testing: In-memory SQLite harness verifies handler lifecycle via unit tests (`go test ./...`). + +## Frontend +- Vite dev server with proxy to `http://localhost:8080` for `/api` paths keeps CORS trivial. +- React Router organizes initial pages (Dashboard, Proxy Hosts, System Status) to mirror Issue roadmap. +- React Query centralizes API caching, invalidation, and loading states. +- Basic layout shell provides left-nav reminiscent of NPM while keeping styling simple (CSS utility file, no design system yet). Future work will slot shadcn/ui components without rewriting data layer. +- Build outputs static assets in `frontend/dist` consumed by Docker multi-stage for production. + +## Data & Persistence +- SQLite chosen for Alpha milestone simplicity; GORM migrates schema automatically on boot (`AutoMigrate`). +- Database path configurable via env to allow persistent volumes in Docker or alternative DB (PostgreSQL/MySQL) when scaling. + +## API Principles +1. **Version Everything** (`/api/v1`). +2. **Stateless**: Each request carries all context; session/story features will rely on cookies/JWT later. +3. **Dependable validation**: Gin binding ensures HTTP 400 responses include validation errors. +4. **Observability**: Gin logging + structured error responses keep early debugging simple; plan to add Zap/zerolog instrumentation during Beta. + +## Local Development Workflow +1. Start backend: `cd backend && go run ./cmd/api`. +2. Start frontend: `cd frontend && npm run dev` (Vite proxy sends API calls to backend automatically). +3. Optional: run both via Docker (see updated Dockerfile) once containers land. +4. Tests: + - Backend: `cd backend && go test ./...` + - Frontend build check: `cd frontend && npm run build` + +## Next Steps +- Layer authentication (Issue #7) once scaffolding lands. +- Expand data model (certificates, access lists) and add migrations. +- Replace basic CSS with component system (e.g., shadcn/ui) + design tokens. +- Compose file bundling backend, frontend assets, Caddy runtime, and SQLite volume. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..9e55d7b5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,387 @@ +# Contributing to CaddyProxyManager+ + +Thank you for your interest in contributing to CaddyProxyManager+! This document provides guidelines and instructions for contributing to the project. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Workflow](#development-workflow) +- [Coding Standards](#coding-standards) +- [Testing Guidelines](#testing-guidelines) +- [Pull Request Process](#pull-request-process) +- [Issue Guidelines](#issue-guidelines) +- [Documentation](#documentation) + +## Code of Conduct + +This project follows a Code of Conduct that all contributors are expected to adhere to: + +- Be respectful and inclusive +- Welcome newcomers and help them get started +- Focus on what's best for the community +- Show empathy towards other community members + +## Getting Started + +-### Prerequisites + +- **Go 1.24+** for backend development +- **Node.js 20+** and npm for frontend development +- Git for version control +- A GitHub account + +### Fork and Clone + +1. Fork the repository on GitHub +2. Clone your fork locally: +```bash +git clone https://github.com/YOUR_USERNAME/CaddyProxyManagerPlus.git +cd CaddyProxyManagerPlus +``` + +3. Add the upstream remote: +```bash +git remote add upstream https://github.com/Wikid82/CaddyProxyManagerPlus.git +``` + +### Set Up Development Environment + +**Backend:** +```bash +cd backend +go mod download +go run ./cmd/seed/main.go # Seed test data +go run ./cmd/api/main.go # Start backend +``` + +**Frontend:** +```bash +cd frontend +npm install +npm run dev # Start frontend dev server +``` + +## Development Workflow + +### Branching Strategy + +- **main** - Production-ready code +- **development** - Main development branch (default) +- **feature/** - Feature branches (e.g., `feature/add-ssl-support`) +- **bugfix/** - Bug fix branches (e.g., `bugfix/fix-import-crash`) +- **hotfix/** - Urgent production fixes + +### Creating a Feature Branch + +Always branch from `development`: + +```bash +git checkout development +git pull upstream development +git checkout -b feature/your-feature-name +``` + +### Commit Message Guidelines + +Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: + +``` +(): + + + +