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
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 devAu 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é :
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=votre-mot-de-passe
ADMIN_API_KEY= # optionnelSans 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é :
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
- 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.
- 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.
- Clés & droits — créer une clé d'API par hôte, ou un identifiant EAB par client ACME.
- 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 :
development | production | |
|---|---|---|
| Politique de mot de passe | aucune | appliquée |
| Directory ACME par défaut | staging | production |
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 :
DB_DIALECT=sqlite
SQLITE_PATH=./data/local-cert.dbDB_DIALECT=postgres
DATABASE_URL=postgres://localcert:secret@localhost:5432/localcertLes 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èretini(qui récupère les processus enfants lancés par le worker ACME et relaie les signaux), avecnpx next start. - Écoute sur le port
3000(HOSTNAME=0.0.0.0,PORT=3000). - Valeurs par défaut :
NODE_ENV=production,APP_ENV=productionetSQLITE_PATH=/app/data/local-cert.db;/app/dataest un volume. - Healthcheck :
GET /api/healthztoutes les 30 s. - Les répertoires
srcetscriptssont 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_SECRETouACME_EMAILn'est évalué pendant la construction.
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-certdocker 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.
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: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 -- Z0123456ABCDEFGHIJKChangez 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 :
| Variable | Défaut | Rôle |
|---|---|---|
DB_DIALECT | sqlite | sqlite ou postgres |
SQLITE_PATH | ./data/local-cert.db | fichier SQLite |
DATABASE_URL | — | chaîne de connexion Postgres ; PG_POOL_MAX (ex. 10) et PGSSL (ex. require) sont facultatifs |
MASTER_KEY | obligatoire | clé AES-256-GCM des secrets au repos ; doit décoder en exactement 32 octets (openssl rand -base64 32) |
JWT_SECRET | obligatoire | signe les JWT de session et d'API (openssl rand -base64 48) |
WEBHOOK_SECRET | — | clé HMAC-SHA256 de signature des webhooks (X-Signature) |
APP_ENV | NODE_ENV | development ou production : politique de mot de passe et directory ACME par défaut |
ACME_ENV | suit APP_ENV | staging ou production ; prioritaire dans les deux sens |
ACME_EMAIL | obligatoire | contact du compte Let's Encrypt |
ACME_DIRECTORY_URL | — | directory amont explicite, remplace celui de l'environnement |
PUBLIC_URL | dérivée | origine 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_RECORDS | 1 | marqueurs TXT de propriété _local-cert.<nom> ; 0 ne garde que le commentaire du ChangeBatch |
JWT_TTL_SECONDS | 3600 | durée de vie des JWT d'API |
SESSION_TTL_SECONDS | 28800 | durée de vie des sessions console |
WORKER_POLL_MS | 10000 | intervalle de scrutation du worker |
WORKER_CONCURRENCY | 2 | ordres traités en parallèle |
RENEW_SWEEP_MS | 21600000 | intervalle 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 :
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.