Hephaestus

Hephaestus is a server-side daemon written in Go, designed for automated management of TLS certificates for domains.

The service runs as a long-living background process (typically via docker-compose) and:

• synchronizes domains from configuration with the database;
• tracks certificate expiration dates;
• automatically renews certificates before they expire;
• operates fully in the background without any HTTP or REST API.

IMPORTANT: Hephaestus is no longer an API service. All behavior is driven by configuration, database state, and an internal scheduler.

---

Key Features

• Automatic creation and renewal of TLS certificates
• Support for multiple domains and alternative (SAN) domains
• Periodic scheduler for certificate renewal
• Persistent state stored in PostgreSQL
• Runs as a daemon / background service
• Configuration via YAML and environment variables

---

How Hephaestus Works

After startup, the service performs two core steps:

1. Domain Synchronization

On startup, Hephaestus:

• reads the list of domains from the configuration file;
• compares them with the current state in the database;
• creates, updates, or deletes domain records in the database to match the configuration.

This allows domain management to be declarative — the configuration file is the single source of truth.

---

2. Certificate Renewal Scheduler

After domain synchronization, the internal scheduler is started:

• runs at a fixed interval defined by certs.renewal_duration;
• checks all active domains stored in the database;
• if a certificate expires in less than 30 days, a renewal process is triggered automatically.

The scheduler continues running as long as the service is alive.

---

Project Architecture

Simplified project structure:

cmd/
  hephaestus/        # application entry point (main)
internal/
  app/               # application bootstrap and wiring
  service/           # core business logic
  scheduler/         # background scheduler
  platform/
    db/              # database access and transactions
    logger/          # logging
migrations/          # SQL migrations
config/              # configuration examples

---

Running the Service

Requirements

• Docker and Docker Compose
• PostgreSQL
• Access to DNS providers (for DNS-01 verification)

---

Running with Docker Compose

Hephaestus is intended to be run via docker-compose.

Example:

docker-compose up -d

The container starts the Hephaestus binary and passes the configuration file path via the CONFIG_PATH environment variable.

---

Configuration

Configuration is defined in a YAML file and loaded on service startup.

General Structure

app:
  name: hephaestus
  version: "2.0.0"

log_level: info

db:
  postgres:
    host: postgres
    port: 5432
    user: hephaestus
    password: secret
    database: hephaestus
    sslmode: disable
    time_zone: UTC
    migration_path: ./migrations

certs:
  storage_dir: /certs
  email: admin@example.com
  renewal_duration: 24h

domains:
  - name: example.com
    alternative_domains:
      - name: www.example.com
        created_by: config
    verification_method: dns
    auto_renew: true
    dns_provider: cloudflare
    created_by: config

---

Configuration Sections

app

app:
  name: hephaestus
  version: "1.0.0"

Informational metadata.

---

log_level

log_level: info

Available values:

• trace
• debug
• info
• warn
• error
• fatal

---

db.postgres

PostgreSQL connection settings.

Required field:

• password

---

certs

certs:
  storage_dir: /certs
  email: admin@example.com
  renewal_duration: 24h

• storage_dir — directory for certificate storage
• email — ACME account email
• renewal_duration — how often the renewal check runs

---

domains

List of domains managed by the service.

domains:
  - name: example.com
    alternative_domains:
      - name: www.example.com
        created_by: config
    verification_method: dns
    auto_renew: true
    dns_provider: cloudflare
    created_by: config

• name — primary domain
• alternative_domains — SAN domains
• verification_method — verification method (e.g. dns)
• auto_renew — enable automatic renewal
• dns_provider — DNS provider name

---

Startup Flow

1. Configuration is loaded (CONFIG_PATH)
2. PostgreSQL connection is established
3. Domains are synchronized with the database
4. Certificate renewal scheduler is started
5. Service runs in the background until stopped

---

Differences from Previous Versions

• REST API removed
• No HTTP endpoints
• Runs as a background daemon
• Domain management via configuration file
• Fully automated lifecycle

---

Logs and Debugging

All logs are written to container stdout/stderr.

To follow logs:

docker logs -f hephaestus

---

License

MIT