LEAPI - Let's Encrypt API

A lightweight HTTP API server for automated SSL/TLS certificate management via Let's Encrypt. Written in pure Lua with no compilation step, LEAPI wraps certbot behind a simple REST API with support for Cloudflare DNS-01 challenges.

Register a domain, and LEAPI handles private key generation, CSR creation, certificate issuance, and renewal -- all through simple HTTP calls that return in under a second.

Features

• REST API for certificate lifecycle management (issue, renew, retrieve, delete)
• Async processing -- certificate operations run in a background worker; API calls never block
• Cloudflare DNS-01 challenges -- no web server configuration required
• Wildcard certificate support via SAN (Subject Alternative Name) entries
• Structured JSON logging with configurable levels
• Zero compilation -- pure Lua, runs anywhere Lua and certbot are installed
• File-based coordination between API and worker processes (no database required)
• Sub-second API responses -- certificate metadata is cached; the API never spawns subprocesses
• Let's Encrypt staging support for testing without hitting rate limits

Quick Start

Prerequisites

Dependency	Install
Lua 5.1+	sudo apt install lua5.4
LuaSocket	sudo apt install lua-socket
certbot	sudo apt install certbot
certbot-dns-cloudflare	sudo apt install python3-certbot-dns-cloudflare
openssl	sudo apt install openssl

1. Clone and configure

git clone https://github.com/youruser/leapi.git
cd leapi

Create a Cloudflare API credentials file:

cat > cloudflare.ini << 'EOF'
dns_cloudflare_api_token = YOUR_CLOUDFLARE_API_TOKEN
EOF
chmod 600 cloudflare.ini

2. Start the server

./api/run.sh 8080

The server starts on port 8080 and automatically spawns a background worker process.

3. Issue a certificate

# Register a domain
curl -X POST http://localhost:8080/domains \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example.com",
    "email": "admin@example.com",
    "cloudflare_ini": "/path/to/cloudflare.ini",
    "domains": ["example.com", "*.example.com"]
  }'

# Poll for completion
curl http://localhost:8080/domains/example.com/status

# Download the certificate
curl http://localhost:8080/domains/example.com/cert

Architecture

LEAPI uses a two-process architecture:

Client  <-->  server.lua (HTTP API)  <-->  domains.json / jobs.json
                                                 ^
                                                 |
              worker.lua (background)  ----------+
                  |
                  +---> csr.lua    (openssl genrsa + openssl req)
                  +---> certbot    (certbot certonly --dns-cloudflare)

• API Process (server.lua): Handles HTTP requests, reads/writes JSON state files, returns fast responses. Never spawns external processes.
• Worker Process (worker.lua): Polls the job queue, generates CSRs, runs certbot, extracts certificate metadata, and writes results back to the state files.

Both processes coordinate exclusively through domains.json and jobs.json on the filesystem, with rename-based file locking for safe concurrent access.

API Endpoints

Method	Path	Description
GET	/health	Health check
GET	/domains	List all domains with cert status
POST	/domains	Register domain and queue cert issuance
GET	/domains/:domain/status	Domain and certificate status
GET	/domains/:domain/cert	Download cert, key, and fullchain PEM
DELETE	/domains/:domain	Remove domain registration
POST	/domains/:domain/renew	Queue certificate renewal
GET	/worker/jobs	List all jobs (monitoring)

See docs/api-reference.md for full API documentation with request/response examples.

Project Structure

leapi/
  api/
    server.lua      # HTTP server entry point
    router.lua      # HTTP parser and route dispatcher
    handlers.lua    # Route handler functions
    config.lua      # Persistent domain configuration store
    queue.lua       # File-backed job queue
    worker.lua      # Background certificate worker
    certbot.lua     # Certbot CLI wrapper
    csr.lua         # CSR and key generation
    certs.lua       # Certificate file access
    log.lua         # Structured JSON logging
    dkjson.lua      # JSON library (bundled)
    run.sh          # Server launcher script
  test/
    run_tests.sh    # Test runner
    test_*.lua      # Unit tests
    integration_staging.lua  # Integration tests
  docs/
    getting-started.md    # Setup guide
    api-reference.md      # HTTP API reference
    lua-modules.md        # Lua module API reference
    configuration.md      # Configuration reference
    architecture.md       # Architecture and design
  cloudflare.ini    # Cloudflare credentials (not tracked)
  domains.json      # Domain state (runtime, not tracked)
  jobs.json         # Job queue (runtime, not tracked)

Documentation

• Getting Started -- Installation, setup, and first certificate
• API Reference -- HTTP endpoint documentation
• Lua Modules -- Internal module API reference
• Configuration -- All configuration options
• Architecture -- System design and internals
• Contributing -- Contribution guidelines

Running Tests

# Unit tests (no network required)
./test/run_tests.sh

# Unit + integration tests (requires certbot + Cloudflare credentials)
./test/run_tests.sh --integration

License

MIT License. See LICENSE for details.