Skip to content
local-cert
Browse the documentation

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

shell
cp .env.example .env.local
openssl rand -base64 32   # -> MASTER_KEY
openssl rand -base64 48   # -> JWT_SECRET

npm install
npm run dev

On 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.

.env
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=your-password
ADMIN_API_KEY=                        # optional

Without 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:

shell
npx tsx scripts/reset-admin.ts admin@example.com <new-password>
# or: npm run admin:reset -- admin@example.com <new-password>

Next steps

  1. 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.
  2. 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.
  3. Keys & access — create one API key per host, or one EAB credential per ACME client.
  4. 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:

developmentproduction
Password policynoneenforced
Default ACME directorystagingproduction

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:

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

Migrations 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 app user, under tini (which reaps the children the ACME worker spawns and forwards signals), with npx next start.
  • Listens on port 3000 (HOSTNAME=0.0.0.0, PORT=3000).
  • Defaults to NODE_ENV=production, APP_ENV=production and SQLITE_PATH=/app/data/local-cert.db; /app/data is a volume.
  • Health check: GET /api/healthz every 30 s.
  • The src and scripts directories 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_SECRET or ACME_EMAIL is evaluated during the build.
Single container, 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

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.

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}
      # 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:
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

# 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 -- Z0123456ABCDEFGHIJK

Change 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:

VariableDefaultRole
DB_DIALECTsqlitesqlite or postgres
SQLITE_PATH./data/local-cert.dbSQLite file
DATABASE_URL—Postgres connection string; PG_POOL_MAX (e.g. 10) and PGSSL (e.g. require) are optional
MASTER_KEYrequiredAES-256-GCM key for secrets at rest; must decode to exactly 32 bytes (openssl rand -base64 32)
JWT_SECRETrequiredsigns session and API JWTs (openssl rand -base64 48)
WEBHOOK_SECRET—HMAC-SHA256 key for webhook signatures (X-Signature)
APP_ENVNODE_ENVdevelopment or production: password policy and default ACME directory
ACME_ENVfollows APP_ENVstaging or production; wins in both directions
ACME_EMAILrequiredLet's Encrypt account contact
ACME_DIRECTORY_URL—explicit upstream directory, overrides the environment default
PUBLIC_URLderivedpublic 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_RECORDS1_local-cert.<name> TXT ownership markers; 0 keeps only the ChangeBatch comment
JWT_TTL_SECONDS3600lifetime of API JWTs
SESSION_TTL_SECONDS28800lifetime of console sessions
WORKER_POLL_MS10000worker polling interval
WORKER_CONCURRENCY2orders processed in parallel
RENEW_SWEEP_MS21600000renewal 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:

.env
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.