mirror of
https://github.com/yusing/godoxy.git
synced 2026-03-23 09:31:02 +01:00
2f2828ec48
- Added information about the loading page (HTML + JS + CSS) and the SSE endpoint for wake events. - Clarified the health monitor implementation and readiness tracking in the architecture overview. - Correct state machine syntax.
98 lines
3.5 KiB
Markdown
98 lines
3.5 KiB
Markdown
______________________________________________________________________
|
|
|
|
## alwaysApply: true
|
|
|
|
# Cursor Rules
|
|
|
|
## Project Overview
|
|
|
|
GoDoxy is a lightweight reverse proxy with WebUI written in Go. It automatically configures routes for Docker containers using labels and provides SSL certificate management, access control, and monitoring capabilities.
|
|
|
|
## Development Commands
|
|
|
|
You should not run any commands to build or run the project.
|
|
|
|
## Documentation
|
|
|
|
If `README.md` exists in the package:
|
|
|
|
- Read it to understand what the package does and how it works.
|
|
- Update it with the changes you made (if any).
|
|
|
|
Update the roort `README.md` if relevant.
|
|
|
|
## Architecture
|
|
|
|
### Core Components
|
|
|
|
1. **Main Entry Point** (`cmd/main.go`)
|
|
|
|
- Initializes configuration and logging
|
|
- Starts the proxy server and WebUI
|
|
|
|
1. **Internal Packages** (`internal/`)
|
|
|
|
- `config/` - Configuration management with YAML files
|
|
- `route/` - HTTP routing and middleware management
|
|
- `docker/` - Docker container integration and auto-discovery
|
|
- `autocert/` - SSL certificate management with Let's Encrypt
|
|
- `acl/` - Access control lists (IP/CIDR, country, timezone)
|
|
- `api/` - REST API server with Swagger documentation
|
|
- `homepage/` - WebUI dashboard and configuration interface
|
|
- `metrics/` - System metrics and uptime monitoring
|
|
- `idlewatcher/` - Container idle detection and power management
|
|
- `watcher/` - File and container state watchers
|
|
|
|
1. **Sub-projects**
|
|
|
|
- `agent/` - System agent for monitoring containers
|
|
- `socket-proxy/` - Docker socket proxy
|
|
|
|
### Key Patterns
|
|
|
|
- **Task Management**: Use `internal/task/task.go` for managing object lifetimes and background operations
|
|
- **Concurrent Maps**: Use `github.com/puzpuzpuz/xsync/v4` instead of maps with mutexes
|
|
- **Error Handling**: Use `pkg/gperr` for nested errors with subjects
|
|
- **Configuration**: YAML-based configuration in `config/` directory
|
|
|
|
## Go Guidelines (from .cursor/rules/go.mdc)
|
|
|
|
1. Use builtin `min` and `max` functions instead of custom helpers
|
|
1. Prefer range-over-integer syntax (`for i := range 10`) over traditional loops
|
|
1. Use `xsync/v4` for concurrent maps instead of map+mutex
|
|
1. Beware of variable shadowing when making edits
|
|
1. Use `internal/task/task.go` for lifetime management:
|
|
- `task.RootTask()` for background operations
|
|
- `parent.Subtask()` for nested tasks
|
|
- `OnFinished()` and `OnCancel()` callbacks for cleanup
|
|
1. Use `pkg/gperr` for complex error scenarios:
|
|
- `gperr.Multiline()` for multiple operation attempts
|
|
- `gperr.NewBuilder()` for collecting multiple errors
|
|
- `gperr.NewGroup() + group.Go()` for collecting errors of multiple concurrent operations
|
|
- `gperr.New().Subject()` for errors with subjects
|
|
|
|
## Configuration Structure
|
|
|
|
- `config/config.yml` - Main configuration
|
|
- `config/middlewares/` - HTTP middleware configurations
|
|
- `config/*.yml` - Provider and service configurations
|
|
- `.env` - Environment variables for ports and settings
|
|
|
|
## Testing
|
|
|
|
Tests are located in `internal/` packages and can be run with:
|
|
|
|
- `make test` - Run all internal package tests
|
|
- Individual package tests: `go test ./internal/config/...`
|
|
- You MUST use `-ldflags="-checklinkname=0"` otherwise compiler will complain
|
|
- prefer `testify/require` over `expect`
|
|
|
|
## Docker Integration
|
|
|
|
GoDoxy integrates with Docker by:
|
|
|
|
1. Listing all containers and reading their labels
|
|
1. Creating routes based on `proxy.aliases` label or container name
|
|
1. Watching for container/config changes and updating automatically
|
|
1. Supporting both Docker and Podman runtimes
|