Installation and configuration
local-cert is a Next.js 16 application: a REST API, an administration console and an ACME server, backed by SQLite or Postgres. This page covers getting an instance running, the environments, the database, the worker, Docker deployment and the environment variables.
Getting started
cp .env.example .env.local
openssl rand -base64 32 # -> MASTER_KEY
openssl rand -base64 48 # -> JWT_SECRET
npm install
npm run devOn first launch, the application applies the schema and then sends you to /setup: every other page redirects there, and the API answers 503 setup_required. The wizard asks for an email and password and creates the administrator account. In development no password policy is enforced: no minimum length, no composition rules, no expiry. In production, the policy described under Environments applies.
An API key is generated along the way and displayed only once, on that page. You can also supply your own.
The wizard never shows up again: a setup.completed_at flag is set in the same transaction that creates the account, and POST /api/setup answers 409 afterwards.
The password is hashed with argon2id (19 MiB, t=2, p=1 — the OWASP baseline). The API key is stored as sha256. No secret is ever written to disk.
Provisioning without the wizard
Set these variables before the first start: the account is created at boot and the wizard is skipped.
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=your-password
ADMIN_API_KEY= # optionalWithout ADMIN_API_KEY, a key is generated and printed once in the startup logs. With it, your string is adopted as is (24 characters minimum, stored hashed).
These variables are only read until setup is done: changing them afterwards has no effect. To rotate the password or the key:
npx tsx scripts/reset-admin.ts admin@example.com <new-password>
# or: npm run admin:reset -- admin@example.com <new-password>Next steps
- Providers — declare the AWS account that hosts your zones: an IAM key pair and, preferably, a role. The wizard generates the trust policy and the permissions policy to paste into IAM, then tests them. See DNS providers.
- Domains — pick a provider, then one of its zones. The console generates the IAM policy that includes this zone and probes the five Route53 calls required: the domain is only added if they pass. See Add a domain.
- Keys & access — create one API key per host, or one EAB credential per ACME client.
- Certificates — issue, follow the logs live, download the
.pem.
The console's Docs page covers all of this step by step, with a guide per reverse proxy and per platform (Traefik, Caddy, Nginx, Kubernetes, Dokploy, Synology…), using your instance's URLs — the same guides as this site.
Environments
APP_ENV (falling back to NODE_ENV) drives the two settings you must never get wrong in production:
development | production | |
|---|---|---|
| Password policy | none | enforced |
| Default ACME directory | staging | production |
Production policy: 12 characters minimum, 256 maximum, at least 3 of the 4 categories (lowercase, uppercase, digit, symbol), common passwords rejected, as well as those containing the account's email address. It applies to the /setup wizard, to provisioning through ADMIN_PASSWORD, and to scripts/reset-admin.ts — not just to the form.
In development, only the empty string is rejected. The setup form reads the active policy from GET /api/setup: no rule is duplicated on the client side.
ACME: ACME_ENV takes precedence in both directions. Leaving it empty makes it follow APP_ENV — that is the recommended default. Forcing it to staging on a production instance is useful while validating a new zone; forcing it to production in development is possible, and rarely a good idea (50 certificates per registered domain per week).
The active environment is shown in the console header and on the setup page.
Database
One schema, two dialects, chosen by environment variable:
DB_DIALECT=sqlite
SQLITE_PATH=./data/local-cert.dbDB_DIALECT=postgres
DATABASE_URL=postgres://localcert:secret@localhost:5432/localcertMigrations are applied automatically at startup (src/lib/db/migrate.ts), or with npm run db:migrate.
Portability: timestamps are ISO-8601 UTC TEXT, booleans are INTEGER 0/1, structures are JSON TEXT. Kysely generates the SQL on both sides.
Worker
The issuance worker and the renewal scheduler run in-process, started by instrumentation.ts. Orders are claimed with a conditional UPDATE on locked_at, and an expired lock is reclaimed after 30 minutes.
Run a single instance: Route53 serializes changes per zone, and two concurrent workers would run into PriorRequestNotComplete. To scale, switch to Postgres, run the web instances with DISABLE_WORKER=1 and keep a single worker process.
Docker deployment
The repository ships a multi-stage Dockerfile (node:26-alpine) and a docker-compose.yml that runs the application against Postgres.
The image
- Runs as an unprivileged
appuser, undertini(which reaps the children the ACME worker spawns and forwards signals), withnpx next start. - Listens on port
3000(HOSTNAME=0.0.0.0,PORT=3000). - Defaults to
NODE_ENV=production,APP_ENV=productionandSQLITE_PATH=/app/data/local-cert.db;/app/datais a volume. - Health check:
GET /api/healthzevery 30 s. - The
srcandscriptsdirectories are included: the operational CLIs (admin:reset,aws:check,openapi:check) run through tsx against the TypeScript sources. - No secret is needed at build time: every route is dynamic, so nothing that reads
MASTER_KEY,JWT_SECRETorACME_EMAILis evaluated during the build.
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
The provided docker-compose.yml starts the application and a postgres:18-alpine database. MASTER_KEY, JWT_SECRET and ACME_EMAIL are required; everything else has a default.
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}
# Optional: a DNS provider declared in the environment.
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}
# Optional: provision the admin account without the /setup wizard.
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
# operational CLIs, inside the container
docker compose exec app npm run admin:reset -- admin@example.com <new-password>
docker compose exec app npm run aws:check -- Z0123456ABCDEFGHIJKChange the Postgres password in both services before exposing anything. In production, put the application behind a TLS reverse proxy that forwards X-Forwarded-Proto / X-Forwarded-Host, or set PUBLIC_URL (for example https://certs.example.com): ACME clients sign the exact URL they call.
Environment variables
The full list, with comments, is in .env.example. The main ones:
| Variable | Default | Role |
|---|---|---|
DB_DIALECT | sqlite | sqlite or postgres |
SQLITE_PATH | ./data/local-cert.db | SQLite file |
DATABASE_URL | — | Postgres connection string; PG_POOL_MAX (e.g. 10) and PGSSL (e.g. require) are optional |
MASTER_KEY | required | AES-256-GCM key for secrets at rest; must decode to exactly 32 bytes (openssl rand -base64 32) |
JWT_SECRET | required | signs session and API JWTs (openssl rand -base64 48) |
WEBHOOK_SECRET | — | HMAC-SHA256 key for webhook signatures (X-Signature) |
APP_ENV | NODE_ENV | development or production: password policy and default ACME directory |
ACME_ENV | follows APP_ENV | staging or production; wins in both directions |
ACME_EMAIL | required | Let's Encrypt account contact |
ACME_DIRECTORY_URL | — | explicit upstream directory, overrides the environment default |
PUBLIC_URL | derived | public origin of the ACME server, no trailing slash, no path; otherwise derived from X-Forwarded-Proto / X-Forwarded-Host (or Host) |
PROVIDER_<HOST>_<LABEL>_<FIELD> | — | DNS providers declared in the environment (below) |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_PROFILE | — | process credentials (standard AWS chain), only for providers without a key pair |
ADMIN_EMAIL, ADMIN_PASSWORD, ADMIN_API_KEY | — | provision the administrator without the wizard |
TAG_RECORDS | 1 | _local-cert.<name> TXT ownership markers; 0 keeps only the ChangeBatch comment |
JWT_TTL_SECONDS | 3600 | lifetime of API JWTs |
SESSION_TTL_SECONDS | 28800 | lifetime of console sessions |
WORKER_POLL_MS | 10000 | worker polling interval |
WORKER_CONCURRENCY | 2 | orders processed in parallel |
RENEW_SWEEP_MS | 21600000 | renewal sweep interval (6 h) |
DISABLE_WORKER | — | 1 on web-only instances |
DNS providers in the environment
Providers are normally created in the console. A provider can also be declared with environment variables, when its credentials must come from the deployment rather than the database. Everything is optional, and the block is repeated with another label for each account:
PROVIDER_AWS_DEFAULT_NAME="Default AWS" # the only mandatory variable of the block
PROVIDER_AWS_DEFAULT_ACCESS_KEY_ID=AKIA… # without the pair: process credentials
PROVIDER_AWS_DEFAULT_SECRET_ACCESS_KEY=…
PROVIDER_AWS_DEFAULT_ROLE_ARN=arn:aws:iam::… # optional
PROVIDER_AWS_DEFAULT_REGION=us-east-1 # optional
PROVIDER_AWS_PROD_NAME="aws-prod" # second account
PROVIDER_GANDI_MAIN_NAME="gandi" # other hosts: same pattern,
PROVIDER_GANDI_MAIN_TOKEN=… # PROVIDER_<OVH|GANDI|GODADDY|GCP>_<LABEL>_<FIELD>The fields per host are listed in .env.example (OVH: ENDPOINT, APPLICATION_KEY, APPLICATION_SECRET, CONSUMER_KEY; Gandi: TOKEN; GoDaddy: API_KEY, API_SECRET; GCP: SERVICE_ACCOUNT_JSON, optional PROJECT_ID).
These providers appear in the console marked environment: they can be tested and their policy generated, but not edited or removed (the API answers 403). Their secret is never written to the database. The DEFAULT label is special: domains declared before providers existed are attached to it at startup. Removing a block hands the provider back to the console, without a key, until it is given one again.
Details per host: DNS providers, AWS, OVHcloud, Gandi, GoDaddy, Google Cloud.