acme-auto/CLAUDE.md

CLAUDE.md

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

Project Overview

CertCenter is a lightweight SSL certificate management platform. It integrates ACME certificate issuance (via certbot), automatic renewal, and multi-server certificate distribution through a Vue 3 WebUI.

Common Commands

# Backend
pip install -r requirements.txt          # Install Python deps
python -m backend.main                   # Start server at :8000

# Frontend
cd frontend && npm install && npm run build && cd ..   # Build for production
cd frontend && npm run dev               # Dev server at :5173 (proxies API to :8000)

# Testing
python -m tests.test_setup               # Validate environment
python -m tests.test_e2e --domain X --ak Y --sk Z   # End-to-end cert issuance test

# Start with hash seed fix (Windows)
set PYTHONHASHSEED=0 && python -m backend.main

Architecture

Backend (FastAPI + SQLAlchemy + SQLite):

• backend/main.py — App entry point, router registration, SPA middleware
• backend/routers/api.py — Client-facing API at /api/* (Bearer token per-server)
• backend/routers/admin.py — Admin API at /admin/api/* (HMAC token auth)
• backend/acme_service.py — ACME operations via certbot subprocess + AliDNS API
• backend/models.py — ORM models: Server, Domain, DeployLog, AcmeConfig, AcmeLog
• backend/templates_cert/ — Jinja2 templates for deploy scripts (bash/PowerShell)

Frontend (Vue 3 + Vite + Tailwind CSS):

• Hash-based routing (/#/path) — no server-side routing needed
• src/App.vue — Login gate + sidebar layout
• src/api/index.js — Axios with auto token injection and 401 handling

Dual Router Design:

• /api/* — Used by deployment scripts on business servers (token per server)
• /admin/api/* — Used by WebUI (single admin user from .env)

ACME Flow: certbot is invoked as a subprocess, not used as a library. DNS-01 challenges are handled by calling AliDNS REST API directly. Wildcard certs (*.example.com) automatically include the bare domain.

Key Technical Decisions

• Python 3.11-3.12 required (3.14 lacks pydantic-core wheels)
• SQLite for zero-dependency deployment
• Version-based sync: clients compare integer version numbers, download only on change
• Self-signed cert bootstrap on first HTTPS boot (client scripts use curl -k)
• Admin auth: HMAC-based tokens (username:expiry:signature), 7-day expiry
• Single admin user configured in .env (ADMIN_USERNAME / ADMIN_PASSWORD)