traefikr: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Traefikr is a Traefik configuration management API that provides a REST API for managing Traefik v3.6 resources (routers, services, middlewares, etc.) with comprehensive JSON schema validation. The backend is written in Go and uses SQLite for persistence.

Build and Development Commands

Docker Development

# Build and start all services (Traefik + Backend)
docker-compose up --build

# Rebuild backend only
docker-compose build backend

# Stop and remove containers
docker-compose down

# Remove backend data volume
docker volume rm traefikr_backend-data

Backend Development

cd backend

# Install dependencies
go mod download

# Build binary
go build -o traefikr .

# Build static binary for production (used in Dockerfile)
CGO_ENABLED=1 GOOS=linux go build \
    -a \
    -ldflags '-linkmode external -extldflags "-static" -s -w' \
    -o main .

# Run locally
TRAEFIKR_DB_PATH=./traefikr.db TRAEFIKR_PORT=8080 TRAEFIK_API_URL=http://localhost:8080 ./traefikr

Testing

# Test authentication flows
./tests/test_auth.sh

# Create test resources
./tests/create_fixed_resources.sh

# Create all middleware types
./tests/create_middlewares.sh

# Delete all resources
./tests/delete_all_resources.sh

Architecture

Dual Authentication System

Traefikr implements two separate authentication mechanisms - this is critical to understand:

1. JWT Authentication (User/Admin access)

   • Used for all CRUD operations on resources
   • Login at /api/auth/login with username/password returns JWT token
   • Token must be passed as Authorization: Bearer <token> header
   • Tokens expire after 24 hours
   • Implemented in middleware/jwt.go

2. API Key Authentication (Traefik polling)

   • ONLY used for /api/config endpoint (Traefik HTTP provider polling)
   • API keys are standalone, not linked to users
   • Created via /api/http/provider endpoint (requires JWT)
   • Passed as x-traefikr-key header
   • Implements conditional authentication: public if no API keys exist (bootstrap mode), requires auth once keys are created
   • Implemented in middleware/auth.go