Aller au contenu
local-cert
Parcourir la documentation

Installation et configuration

local-cert est une application Next.js 16 : une API REST, une console d'administration et un serveur ACME, sur SQLite ou Postgres. Cette page couvre le démarrage d'une instance, les environnements, la base de données, le worker, le déploiement Docker et les variables d'environnement.

Démarrage

shell
git clone https://github.com/resourcepool/local-cert.git
cd local-cert
cp .env.example .env.local
openssl rand -base64 32   # -> MASTER_KEY
openssl rand -base64 48   # -> JWT_SECRET

npm install
npm run dev

Au premier lancement, l'application applique le schéma puis vous envoie sur /setup — toutes les autres pages y redirigent, et l'API répond 503 setup_required. Le wizard demande email + mot de passe et crée le compte administrateur. En développement, aucune politique de mot de passe n'est imposée : ni longueur minimale, ni composition, ni expiration. En production, la politique décrite dans Environnements s'applique.

Une clé d'API est générée au passage et affichée une seule fois, sur cette page. Vous pouvez aussi fournir la vôtre.

Le wizard ne se réaffiche jamais : un drapeau setup.completed_at est posé dans la même transaction que la création du compte, et POST /api/setup répond 409 ensuite.

Le mot de passe est haché en argon2id (19 MiB, t=2, p=1 — baseline OWASP). La clé d'API est stockée en sha256. Aucun secret n'est écrit sur disque.

Provisionnement sans wizard

Définissez ces variables avant le premier démarrage — le compte est créé au boot et le wizard est court-circuité :

.env
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=votre-mot-de-passe
ADMIN_API_KEY=                        # optionnel

Sans ADMIN_API_KEY, une clé est générée et affichée une fois dans les logs de démarrage. Avec, votre chaîne est adoptée telle quelle (24 caractères minimum, stockée hachée).

Ces variables ne sont lues que tant que le setup n'est pas fait : les changer ensuite n'a aucun effet. Pour faire tourner le mot de passe ou la clé :

shell
npx tsx scripts/reset-admin.ts admin@example.com <nouveau-mot-de-passe>
# ou : npm run admin:reset -- admin@example.com <nouveau-mot-de-passe>

Ensuite

  1. Providers — déclarer le compte AWS qui héberge vos zones : une paire de clés IAM et, de préférence, un rôle. L'assistant génère la politique de confiance et la politique de droits à coller dans IAM, puis teste. Voir Providers DNS.
  2. Domaines — choisir un provider, puis une de ses zones. La console génère la politique IAM qui inclut cette zone et sonde les cinq appels Route53 nécessaires : le domaine n'est ajouté que s'ils passent. Voir Ajouter un domaine.
  3. Clés & droits — créer une clé d'API par hôte, ou un identifiant EAB par client ACME.
  4. Certificats — émettre, suivre les logs en direct, télécharger le .pem.

La page Docs de la console reprend tout cela pas à pas, avec un guide par reverse proxy et par plateforme (Traefik, Caddy, Nginx, Kubernetes, Dokploy, Synology…), aux URLs de votre instance — les mêmes guides que sur ce site.

Environnements

APP_ENV (à défaut NODE_ENV) pilote les deux réglages qu'il ne faut jamais se tromper en production :

developmentproduction
Politique de mot de passeaucuneappliquée
Directory ACME par défautstagingproduction

Politique de production : 12 caractères minimum, 256 maximum, au moins 3 des 4 catégories (minuscule, majuscule, chiffre, symbole), refus des mots de passe courants et de ceux contenant l'adresse e-mail du compte. Elle s'applique au wizard /setup, au provisionnement par ADMIN_PASSWORD, et à scripts/reset-admin.ts — pas seulement au formulaire.

En développement, seule la chaîne vide est refusée. Le formulaire de setup lit la politique active depuis GET /api/setup : il n'y a pas de règle dupliquée côté client.

ACME : ACME_ENV reste prioritaire dans les deux sens. Le laisser vide fait suivre APP_ENV — c'est le défaut recommandé. Le forcer à staging sur une instance de production est utile le temps de valider une nouvelle zone ; le forcer à production en développement est possible, et rarement une bonne idée (50 certificats par domaine enregistré et par semaine).

L'environnement actif est affiché dans l'en-tête de la console et sur la page de setup.

Base de données

Un seul schéma, deux dialectes, choisis par variable d'environnement :

SQLite
DB_DIALECT=sqlite
SQLITE_PATH=./data/local-cert.db
Postgres
DB_DIALECT=postgres
DATABASE_URL=postgres://localcert:secret@localhost:5432/localcert

Les migrations s'appliquent automatiquement au démarrage (src/lib/db/migrate.ts), ou via npm run db:migrate.

Portabilité : les timestamps sont du TEXT ISO-8601 UTC, les booléens des INTEGER 0/1, les structures du TEXT JSON. Kysely génère le SQL des deux côtés.

Worker

Le worker d'émission et le planificateur de renouvellement tournent in-process, démarrés par instrumentation.ts. Les ordres sont pris par UPDATE conditionnel sur locked_at, et un verrou expiré est récupéré au bout de 30 min.

Faites tourner une seule instance : Route53 sérialise les changements par zone, deux workers concurrents se prendraient des PriorRequestNotComplete. Pour scaler, passez à Postgres, lancez les instances web avec DISABLE_WORKER=1 et gardez un unique processus worker.

Déploiement Docker

Le dépôt fournit un Dockerfile multi-étapes (node:26-alpine) et un docker-compose.yml qui fait tourner l'application avec Postgres.

L'image

  • Tourne sous un utilisateur non privilégié app, derrière tini (qui récupère les processus enfants lancés par le worker ACME et relaie les signaux), avec npx next start.
  • Écoute sur le port 3000 (HOSTNAME=0.0.0.0, PORT=3000).
  • Valeurs par défaut : NODE_ENV=production, APP_ENV=production et SQLITE_PATH=/app/data/local-cert.db ; /app/data est un volume.
  • Healthcheck : GET /api/healthz toutes les 30 s.
  • Les répertoires src et scripts sont embarqués : les CLI d'exploitation (admin:reset, aws:check, openapi:check) passent par tsx sur les sources TypeScript.
  • Aucun secret n'est nécessaire au build : toutes les routes sont dynamiques, rien de ce qui lit MASTER_KEY, JWT_SECRET ou ACME_EMAIL n'est évalué pendant la construction.
Un seul conteneur, SQLite
docker build -t local-cert .
docker run -d --name local-cert -p 3000:3000 \
  -v local-cert-data:/app/data \
  -e MASTER_KEY="$MASTER_KEY" -e JWT_SECRET="$JWT_SECRET" \
  -e ACME_EMAIL=ops@example.com \
  local-cert

docker compose

Le docker-compose.yml fourni démarre l'application et une base postgres:18-alpine. MASTER_KEY, JWT_SECRET et ACME_EMAIL sont obligatoires ; tout le reste a une valeur par défaut.

docker-compose.yml
services:
  app:
    build: .
    ports: ['3000:3000']
    environment:
      DB_DIALECT: postgres
      DATABASE_URL: postgres://localcert:localcert@db:5432/localcert
      MASTER_KEY: ${MASTER_KEY:?generate with: openssl rand -base64 32}
      JWT_SECRET: ${JWT_SECRET:?generate with: openssl rand -base64 48}
      WEBHOOK_SECRET: ${WEBHOOK_SECRET:-}
      APP_ENV: ${APP_ENV:-production}
      ACME_ENV: ${ACME_ENV:-}
      ACME_EMAIL: ${ACME_EMAIL:?required}
      TAG_RECORDS: ${TAG_RECORDS:-1}
      # Optionnel : un provider DNS déclaré dans l'environnement.
      PROVIDER_AWS_DEFAULT_NAME: ${PROVIDER_AWS_DEFAULT_NAME:-}
      PROVIDER_AWS_DEFAULT_ACCESS_KEY_ID: ${PROVIDER_AWS_DEFAULT_ACCESS_KEY_ID:-}
      PROVIDER_AWS_DEFAULT_SECRET_ACCESS_KEY: ${PROVIDER_AWS_DEFAULT_SECRET_ACCESS_KEY:-}
      PROVIDER_AWS_DEFAULT_ROLE_ARN: ${PROVIDER_AWS_DEFAULT_ROLE_ARN:-}
      PROVIDER_AWS_DEFAULT_REGION: ${PROVIDER_AWS_DEFAULT_REGION:-us-east-1}
      # Optionnel : provisionner le compte admin sans le wizard /setup.
      ADMIN_EMAIL: ${ADMIN_EMAIL:-}
      ADMIN_PASSWORD: ${ADMIN_PASSWORD:-}
      ADMIN_API_KEY: ${ADMIN_API_KEY:-}
    volumes:
      - certdata:/app/data
    depends_on:
      db: { condition: service_healthy }
    restart: unless-stopped

  db:
    image: postgres:18-alpine
    environment:
      POSTGRES_USER: localcert
      POSTGRES_PASSWORD: localcert
      POSTGRES_DB: localcert
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U localcert']
      interval: 5s
      timeout: 3s
      retries: 10
    restart: unless-stopped

volumes:
  certdata:
  pgdata:
shell
cat > .env <<EOF
MASTER_KEY=$(openssl rand -base64 32)
JWT_SECRET=$(openssl rand -base64 48)
ACME_EMAIL=ops@example.com
ACME_ENV=staging
EOF

docker compose up -d --build

# CLI d'exploitation, dans le conteneur
docker compose exec app npm run admin:reset -- admin@example.com <nouveau-mot-de-passe>
docker compose exec app npm run aws:check -- Z0123456ABCDEFGHIJK

Changez le mot de passe Postgres dans les deux services avant d'exposer quoi que ce soit. En production, placez l'application derrière un reverse proxy TLS qui transmet X-Forwarded-Proto / X-Forwarded-Host, ou fixez PUBLIC_URL (par exemple https://certs.example.com) : les clients ACME signent l'URL exacte qu'ils appellent.

Variables d'environnement

La liste complète, commentée, est dans .env.example. Les principales :

VariableDéfautRôle
DB_DIALECTsqlitesqlite ou postgres
SQLITE_PATH./data/local-cert.dbfichier SQLite
DATABASE_URL—chaîne de connexion Postgres ; PG_POOL_MAX (ex. 10) et PGSSL (ex. require) sont facultatifs
MASTER_KEYobligatoireclé AES-256-GCM des secrets au repos ; doit décoder en exactement 32 octets (openssl rand -base64 32)
JWT_SECRETobligatoiresigne les JWT de session et d'API (openssl rand -base64 48)
WEBHOOK_SECRET—clé HMAC-SHA256 de signature des webhooks (X-Signature)
APP_ENVNODE_ENVdevelopment ou production : politique de mot de passe et directory ACME par défaut
ACME_ENVsuit APP_ENVstaging ou production ; prioritaire dans les deux sens
ACME_EMAILobligatoirecontact du compte Let's Encrypt
ACME_DIRECTORY_URL—directory amont explicite, remplace celui de l'environnement
PUBLIC_URLdérivéeorigine publique du serveur ACME, sans slash final ni chemin ; à défaut, dérivée de X-Forwarded-Proto / X-Forwarded-Host (ou Host)
PROVIDER_<HÉBERGEUR>_<LIBELLÉ>_<CHAMP>—providers DNS déclarés dans l'environnement (ci-dessous)
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_PROFILE—credentials du processus (chaîne AWS standard), uniquement pour les providers sans paire de clés
ADMIN_EMAIL, ADMIN_PASSWORD, ADMIN_API_KEY—provisionner l'administrateur sans le wizard
TAG_RECORDS1marqueurs TXT de propriété _local-cert.<nom> ; 0 ne garde que le commentaire du ChangeBatch
JWT_TTL_SECONDS3600durée de vie des JWT d'API
SESSION_TTL_SECONDS28800durée de vie des sessions console
WORKER_POLL_MS10000intervalle de scrutation du worker
WORKER_CONCURRENCY2ordres traités en parallèle
RENEW_SWEEP_MS21600000intervalle du balayage de renouvellement (6 h)
DISABLE_WORKER—1 sur les instances web seules

Providers DNS dans l'environnement

Les providers se créent normalement dans la console. Un provider peut aussi être déclaré par variables d'environnement, quand ses credentials doivent venir du déploiement plutôt que de la base. Tout est facultatif, et le bloc se répète avec un autre libellé pour chaque compte :

.env
PROVIDER_AWS_DEFAULT_NAME="Default AWS"          # seule variable obligatoire du bloc
PROVIDER_AWS_DEFAULT_ACCESS_KEY_ID=AKIA…         # sans la paire : credentials du processus
PROVIDER_AWS_DEFAULT_SECRET_ACCESS_KEY=…
PROVIDER_AWS_DEFAULT_ROLE_ARN=arn:aws:iam::…     # facultatif
PROVIDER_AWS_DEFAULT_REGION=us-east-1            # facultatif

PROVIDER_AWS_PROD_NAME="aws-prod"                # second compte

PROVIDER_GANDI_MAIN_NAME="gandi"                 # autres hébergeurs : même schéma,
PROVIDER_GANDI_MAIN_TOKEN=…                      # PROVIDER_<OVH|GANDI|GODADDY|GCP>_<LIBELLÉ>_<CHAMP>

La liste des champs par hébergeur est dans .env.example (OVH : ENDPOINT, APPLICATION_KEY, APPLICATION_SECRET, CONSUMER_KEY ; Gandi : TOKEN ; GoDaddy : API_KEY, API_SECRET ; GCP : SERVICE_ACCOUNT_JSON, PROJECT_ID facultatif).

Ces providers apparaissent dans la console marqués « environnement » : on peut les tester et générer leur politique, pas les modifier ni les retirer (l'API répond 403). Leur secret n'est jamais écrit en base. Le libellé DEFAULT a une particularité : les domaines déclarés avant l'arrivée des providers y sont rattachés au démarrage. Retirer un bloc rend le provider à la console, sans clé, jusqu'à ce qu'on lui en redonne une.

Le détail par hébergeur : Providers DNS, AWS, OVHcloud, Gandi, GoDaddy, Google Cloud.