Modern Docker Management, Designed for Everyone
Go composecontainer-managementcontainersdockerdocker-composedocker-managementgoself-hostedsveltekittypescriptweb-ui
chore: update copilot instructions to follow new codebase patterns
Kyle Mendellc56100dde076
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.mdindex ca832b516..a341453eb 100644--- a/.github/copilot-instructions.md+++ b/.github/copilot-instructions.md@@ -1,268 +1,250 @@-# Arcane — Copilot / AI agent quick instructions+# Arcane AI Agent Instructions-Purpose: Get an AI coding agent productive quickly. Make small, well-scoped edits, follow repository wiring, and run the provided dev script for integrated testing, dont make useless comments that dont help the codebase.+Arcane is a modern Docker management UI with a **Go backend** (Huma v2 API), **SvelteKit frontend** (Svelte 5), and an optional headless agent. Three Go modules unified via `go.work`: `backend/`, `cli/`, `types/`.-Quick architecture summary+## Development Environment-- Backend: Go (cmd/main.go) + Gin. App wiring and DI live in `internal/bootstrap/`. DB via GORM; models under `internal/models/`. Handlers in `internal/api/*_handler.go`, services in `internal/services/*_service.go`.-- Frontend: SvelteKit (frontend/src) using Svelte 5 syntax (runes). Routes: `frontend/src/routes/`. Shared components: `frontend/src/lib/components/`.-- Integration: Docker + local containers. Entry scripts: `scripts/docker/entrypoint.sh` and `docker/entrypoint.sh`.--Essential workflows (commands)--- Start dev env (recommended): `./scripts/development/dev.sh start` (VS Code task "Start").-- Stop / Restart / Rebuild: same script with `stop|restart|rebuild|clean`.-- Frontend local build: use `frontend/package.json` scripts (or run inside the dev containers).-- Tests: Playwright E2E specs in `tests/spec/*.ts`; helpers in `tests/` and `setup/`.--Project-specific conventions (follow exactly)--- Keep HTTP handlers thin — push business logic into `internal/services/*_service.go`.-- File naming: `*_handler.go`, `*_service.go`, DTOs in `internal/dto/`.-- Use DTOs for API boundaries; frontend also has DTOs under `frontend/src/lib/dto/`.-- Database models include `BaseModel` fields and may implement `TableName()` for custom names.-- Svelte 5: use `$state()/$effect()/$derived()` and `let { prop } = $props()` patterns. Frontend files use Svelte 5 runes consistently.+```bash+./scripts/development/dev.sh start # Start Docker-based dev environment (hot reload)+./scripts/development/dev.sh stop|restart|rebuild|clean|logs+```-Where to look when adding features or debugging+- Frontend: http://localhost:3000 (Vite HMR)+- Backend: http://localhost:3552 (Air hot reload)-- Startup & wiring: `internal/bootstrap/` -> `cmd/main.go`.-- API endpoints and handlers: `internal/api/`.-- Services and business logic: `internal/services/`.-- Frontend pages & components: `frontend/src/routes/` and `frontend/src/lib/components/`.-- Docker/dev scripts: `scripts/development/dev.sh`, `docker-compose*.yml`, and `scripts/docker/entrypoint.sh`.+## Architecture Overview-Tests & CI notes+### Backend (`backend/`)-- Playwright E2E lives in `tests/` and is configured via `tests/package.json` and `playwright.config.ts`.-- Backend unit tests should mock Docker client calls where possible.+```+internal/+├── bootstrap/ # App initialization & DI wiring — START HERE for understanding how services connect+├── huma/handlers/ # HTTP handlers (Huma v2) — thin wrappers that call services+├── services/ # Business logic — *_service.go files contain all domain logic+├── models/ # GORM database models (include BaseModel for UUID, timestamps)+├── config/ # Environment configuration+└── middleware/ # Auth, logging, rate limiting+```-Safe-edit checklist for AI agents+**Key patterns:**+- Handlers are thin: extract user from context, call service, return response+- Services receive dependencies via constructor injection (see [bootstrap.go](backend/internal/bootstrap/bootstrap.go))+- Use `slog` for structured logging with context+- Error wrapping: `fmt.Errorf("context: %w", err)`-1. Make minimal changes and run `go build ./...` if you change backend code.-2. Run frontend build (`pnpm -w -C frontend build`) or use the dev script for integrated runs.-3. Do not commit secrets or change environment wiring; use `dev.sh` for env setup.+### Frontend (`frontend/src/`)-Examples (copyable patterns)+```+routes/(app)/ # Main app pages (dashboard, containers, images, etc.)+routes/(auth)/ # Auth pages+lib/components/ # Reusable Svelte components (shadcn-svelte based)+lib/services/ # API service classes extending BaseAPIService+lib/stores/ # Svelte stores (*.store.svelte files use runes)+lib/types/ # TypeScript types+```-- New handler: add `internal/api/foo_handler.go` that binds request DTO, calls `services.NewFooService(db, docker).Create(...)`, and returns JSON.-- New service: `internal/services/foo_service.go` that accepts DB and Docker clients from bootstrap and implements business logic; return wrapped errors with `fmt.Errorf("context: %w", err)`.+### Shared Types (`types/`)-If unclear+Domain types shared between backend and CLI. Each domain has its own package (e.g., `types/container/`, `types/image/`).-- Ask to inspect a specific file (path) and whether you want me to run build/tests. I'll run them and return results.+## Critical Patterns-— End of concise instructions —+### Svelte 5 ONLY — No Svelte 4 Syntax-# Arcane Docker Management UI - Copilot Instructions+```svelte+<!-- Props: use $props() -->+let { prop1, prop2 }: { prop1: string; prop2?: number } = $props();-## Project Overview+<!-- State: use $state() -->+let count = $state(0);-Arcane is a modern, full-stack Docker management UI built with SvelteKit frontend and Go backend. It provides comprehensive Docker environment management including containers, images, volumes, networks, stacks, and image update tracking.+<!-- Derived values: use $derived() or $derived.by() -->+let doubled = $derived(count * 2);+let computed = $derived.by(() => complexCalculation());-## Architecture & Tech Stack+<!-- Side effects: use $effect() -->+$effect(() => { /* runs when dependencies change */ });+```-### Backend (Go)+**NEVER use:** `export let`, `on:click` (use `onclick`), `$:`, `$$props`, `$$restProps`, slot syntax-- **Framework**: Gin web framework with Go 1.24.3+-- **Database**: GORM with PostgreSQL/SQLite support-- **Structure**: Clean architecture with bootstrap pattern-- **Authentication**: JWT + optional OIDC integration-- **Jobs**: gocron v2 for scheduled tasks-- **Docker**: Official Docker SDK integration+Example component: [job-card.svelte](frontend/src/lib/components/job-card/job-card.svelte)-### Frontend (SvelteKit + TypeScript)+### API Service Pattern-- **Framework**: SvelteKit with Svelte 5 syntax-- **UI**: shadcn-svelte components + Tailwind CSS-- **Icons**: Lucide Svelte-- **State**: Svelte 5 runes ($state, $effect, $derived)-- **API**: Axios for HTTP requests-- **Build**: Vite with static adapter+Frontend services extend `BaseAPIService` and use `environmentStore` for multi-environment support:-## Code Conventions & Patterns+```typescript+export class ContainerService extends BaseAPIService {+ async getContainers(options?: SearchPaginationSortRequest) {+ const envId = await environmentStore.getCurrentEnvironmentId();+ const params = transformPaginationParams(options);+ return this.api.get(`/environments/${envId}/containers`, { params });+ }+}+export const containerService = new ContainerService();+```-### Backend (Go)+### Huma Handler Pattern-#### File Organization+Handlers use typed input/output structs with struct tags for validation:+```go+type ListContainersInput struct {+ EnvironmentID string `path:"id" doc:"Environment ID"`+ Search string `query:"search" doc:"Search query"`+ Limit int `query:"limit" default:"20" doc:"Limit"`+}```-backend/-├── cmd/main.go # Application entry point-├── internal/-│ ├── bootstrap/ # App initialization (DI container pattern)-│ ├── api/ # HTTP handlers (*_handler.go)-│ ├── services/ # Business logic (*_service.go)-│ ├── models/ # Database models-│ ├── dto/ # Data transfer objects-│ ├── database/ # DB connection & migrations-│ ├── config/ # Configuration management-│ ├── middleware/ # HTTP middleware-│ ├── utils/ # Utility functions-│ └── job/ # Background job scheduling-```--#### Naming Conventions-- **Handlers**: `*_handler.go` with methods like `List`, `Create`, `Update`, `Delete`-- **Services**: `*_service.go` with business logic implementation-- **Models**: Singular names (e.g., `Container`, `Image`, `Stack`)-- **Package names**: Lowercase, single word when possible+Register handlers in [backend/internal/huma/handlers/](backend/internal/huma/handlers/).-#### Database Models+## Testing-- Use GORM annotations for relationships and constraints-- Include `BaseModel` for common fields (ID, CreatedAt, UpdatedAt)-- Implement `TableName()` method for custom table names-- Use proper foreign key relationships with preloading+```bash+# Backend unit tests+cd backend && go test ./...-#### API Patterns+# E2E tests (Playwright)+pnpm test # from project root-- RESTful endpoints with proper HTTP status codes-- Use DTOs for request/response transformation-- Implement pagination with `SortedPaginationRequest`-- Return consistent JSON error responses-- Use Gin binding for request validation+# Frontend type checking+pnpm -C frontend check:ci+```-#### Error Handling+Backend tests use in-memory SQLite and testify. See [auth_service_test.go](backend/internal/services/auth_service_test.go) for patterns.-- Return meaningful HTTP status codes-- Use structured logging with `slog`-- Wrap errors with context using `fmt.Errorf`-- Handle Docker API errors gracefully+## Anti-Patterns to Avoid-### Frontend (SvelteKit + TypeScript)+- Business logic in handlers — move to services+- Svelte 4 syntax anywhere+- Hardcoded registry logic — use generic OCI patterns+- TypeScript `any` without justification+- Unnecessary comments explaining obvious code-#### File Organization+## Container Registry Integration-```-frontend/src/-├── routes/ # SvelteKit file-based routing-├── lib/-│ ├── components/ # Reusable Svelte components-│ ├── services/api/ # API service classes-│ ├── stores/ # Svelte stores-│ ├── types/ # TypeScript type definitions-│ ├── dto/ # Frontend DTOs-│ ├── utils/ # Utility functions-│ └── constants.ts # App constants-```+- Use generic authentication (bearer tokens, basic auth)+- Support multiple providers (Docker Hub, GHCR, custom OCI)+- Use case-insensitive header checking-#### Svelte 5 Conventions+## Multi-Environment Support-- **Props**: Use `let { prop1, prop2 } = $props()` destructuring-- **State**: Use `$state()` for reactive variables-- **Effects**: Use `$effect()` for side effects-- **Derived**: Use `$derived()` for computed values-- **Event handlers**: Use `on*` props or inline handlers+Arcane supports managing multiple Docker environments (local + remote agents). The frontend uses `environmentStore` to track the active environment:-#### Component Patterns+```typescript+// LOCAL_DOCKER_ENVIRONMENT_ID = '0' is the local Docker socket+const envId = await environmentStore.getCurrentEnvironmentId();-- **Reusable components**: Place in `/lib/components/`-- **Page components**: Use `+page.svelte` in routes-- **Layout components**: Use `+layout.svelte` for shared layouts-- **Loading states**: Implement with `loading` props and spinners-- **Error boundaries**: Handle errors gracefully with user feedback+// All API calls include environment ID in the path+this.api.get(`/environments/${envId}/containers`);+```-#### TypeScript Usage+**Key patterns:**+- Environment ID `"0"` = local Docker connection+- Remote environments connect via agents (standard or edge)+- `environmentStore.ready` is a Promise — await before accessing environment-specific data+- When environment changes, resource detail pages redirect to list pages (resources don't exist across environments)-- Define interfaces for all data structures-- Use strict type checking-- Export types from dedicated `*.type.ts` files-- Use generic types for reusable components+See [environment.store.svelte.ts](frontend/src/lib/stores/environment.store.svelte.ts) for implementation.-#### API Integration+## Background Job Scheduling-- Create service classes in `/lib/services/api/`-- Use Axios with proper error handling-- Implement request/response DTOs-- Use async/await patterns consistently+Jobs use cron-based scheduling via `robfig/cron/v3`. To add a new job:-#### Styling+1. Implement the `Job` interface in `backend/pkg/scheduler/`:-- Use Tailwind CSS classes-- Follow shadcn-svelte component patterns-- Implement dark/light mode support-- Use CSS variables for theming+```go+type Job interface {+ Name() string // Unique job identifier+ Schedule(ctx context.Context) string // Cron expression (6-field with seconds)+ Run(ctx context.Context) // Job execution logic+}+```-## Development Guidelines+2. Create job with service dependencies:-### General Rules+```go+type MyJob struct {+ myService *services.MyService+ settingsService *services.SettingsService+}-- **No unnecessary comments**: Code should be self-documenting-- **Clean imports**: Group and sort imports logically-- **Error handling**: Always handle errors appropriately-- **Type safety**: Use TypeScript strictly on frontend-- **Performance**: Implement pagination, lazy loading, and efficient updates+func NewMyJob(myService *services.MyService, settings *services.SettingsService) *MyJob {+ return &MyJob{myService: myService, settingsService: settings}+}-### Backend Specific+func (j *MyJob) Schedule(ctx context.Context) string {+ return j.settingsService.GetStringSetting(ctx, "myJobInterval", "0 0 * * * *") // hourly default+}+```-- Use dependency injection through bootstrap pattern-- Implement proper service layer separation-- Use GORM relationships efficiently with preloading-- Handle Docker API rate limits and timeouts-- Implement proper logging with structured data+3. Register in [jobs_bootstrap.go](backend/internal/bootstrap/jobs_bootstrap.go):-### Frontend Specific+```go+myJob := pkg_scheduler.NewMyJob(appServices.MyService, appServices.Settings)+newScheduler.RegisterJob(myJob)+```-- **Always use Svelte 5 syntax** (runes, new event handling)-- Implement proper loading and error states-- Use reactive patterns efficiently-- Follow SvelteKit best practices for SSR/hydration-- Implement proper form validation+**Note:** Cron uses 6 fields (with seconds): `"0 0 * * * *"` = every hour at :00:00-### Database+## Database Patterns (GORM)-- Use migrations for schema changes-- Implement proper indexing for performance-- Use foreign key constraints-- Handle soft deletes where appropriate+### BaseModel-### Security+All models embed `BaseModel` for UUID primary key and timestamps:-- Validate all user inputs-- Use proper authentication middleware-- Implement CORS correctly-- Encrypt sensitive configuration data-- Follow Docker security best practices+```go+type MyModel struct {+ models.BaseModel // ID, CreatedAt, UpdatedAt+ Name string `json:"name" gorm:"column:name" sortable:"true"`+ ForeignID string `json:"foreignId" gorm:"column:foreign_id"`+ Related *OtherModel `json:"related,omitempty" gorm:"foreignKey:ForeignID"`+}-### Testing+func (MyModel) TableName() string { return "my_models" }+```-- Write Playwright E2E tests for critical user flows-- Test API endpoints thoroughly-- Mock external Docker API calls in tests-- Use proper test data setup and teardown+### Relationships & Preloading-## Anti-Patterns to Avoid+Always use `Preload` for eager loading relationships:-### Backend+```go+// Single preload+s.db.WithContext(ctx).Preload("Registry").Where("id = ?", id).First(&template)-- Don't put business logic in handlers-- Don't use global variables for state-- Don't ignore database transaction boundaries-- Don't hardcode registry-specific logic (use generic patterns)+// Multiple preloads+s.db.WithContext(ctx).+ Preload("Repository").+ Preload("Project").+ Where("id = ?", id).First(&sync)+```-### Frontend+### Custom Types-- Don't use Svelte 4 syntax (no export let, on:click, etc.)-- Don't ignore loading/error states-- Don't create overly complex component hierarchies-- Don't bypass type checking with `any`+Use `models.JSON` for arbitrary JSON fields and `models.StringSlice` for string arrays — both implement `driver.Valuer` and `sql.Scanner`.-### General+## Edge Agent Mode-- Don't add unnecessary comments or console.log statements-- Don't ignore error handling-- Don't create tight coupling between layers-- Don't commit sensitive configuration data+Edge agents connect to a central Arcane manager via WebSocket tunnel, allowing management of Docker hosts behind NAT/firewalls.-## Container Registry Integration+**Architecture:**+- Manager: Receives tunnel connections, proxies HTTP requests over WebSocket+- Agent: Connects outbound to manager, executes requests locally-When working with container registries:+**Configuration** (agent side):+```bash+ARCANE_EDGE_AGENT=true+ARCANE_MANAGER_API_URL=https://manager.example.com+ARCANE_AGENT_TOKEN=<api-key>+```-- Use generic authentication patterns, not registry-specific hardcoding-- Handle different authentication methods (bearer tokens, basic auth)-- Implement proper error handling for network timeouts-- Support multiple registry providers (Docker Hub, GHCR, custom OCI)-- Use case-insensitive header checking for registry responses+**Message types** (see [tunnel.go](backend/internal/utils/edge/tunnel.go)):+- `request` / `response`: HTTP request/response proxying+- `heartbeat` / `heartbeat_ack`: Connection keepalive+- `ws_start` / `ws_data` / `ws_close`: WebSocket streaming (logs, stats)-This codebase emphasizes clean architecture, type safety, and maintainable patterns. Follow these guidelines to ensure consistency and quality across all contributions.+**When implementing agent features:**+- Check `cfg.AgentMode` to skip manager-only logic (e.g., environment health checks)+- Agent auto-pairs with manager on startup if token is configured+- Edge connections are stateless — each request is independent