diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 9f49b61..59005f7 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -17,3 +17,8 @@ repos: language: system pass_filenames: false types: [go] + + - repo: https://github.com/gitleaks/gitleaks + rev: v8.30.1 + hooks: + - id: gitleaks diff --git a/README.md b/README.md index 1958b53..c53de03 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,17 @@ ## How It Works -When a client successfully completes an ACME challenge, `acme-proxy` forwards the certificate signing request to an external certificate authority (CA) that supports External Account Binding (EAB). The external CA signs the certificate and returns it to the client through `acme-proxy`. +`acme-proxy` runs as an ACME server inside your enterprise environment, acting as an intermediary between your internal infrastructure and an external certificate authority service (such as Sectigo). When a client successfully completes an ACME challenge, `acme-proxy` forwards the certificate signing request to an external certificate authority (CA) that supports External Account Binding (EAB). The external CA signs the certificate and returns it to the client through `acme-proxy`. + +**Certificate Request Flow:** + +1. Your internal server (behind a firewall perimeter) requests a certificate from `acme-proxy` using standard ACME clients like certbot, acme.sh or cert-manager.io if you're using Kubernetes. +2. `acme-proxy` presents cryptographic challenges to verify domain ownership +3. Once validation succeeds, `acme-proxy` forwards the certificate signing request to your external CA using External Account Binding (EAB) +4. The external CA signs the certificate +5. `acme-proxy` retrieves the certificate bundle and returns it to your server + +![sequence diagram](docs/assets/highlevel-flow.png) **Note:** LetsEncrypt does not support EAB. However, commercial CAs such as Sectigo and ZeroSSL do. @@ -40,20 +50,6 @@ Using ACME with commercial CAs in enterprise environments provides several advan - Leverage standard ACME clients (Certbot, acme.sh, cert-manager.io) for certificate issuance, automatic renewals. - Enable self-service certificate requests for development teams -## ACME Proxy Workflow - -`acme-proxy` runs as an ACME server inside your enterprise environment, acting as an intermediary between your internal infrastructure and an external certificate authority service (such as Sectigo). - -**Certificate Request Flow:** - -1. Your internal server (behind a firewall perimeter) requests a certificate from `acme-proxy` using standard ACME clients like certbot, acme.sh or cert-manager.io if you're using Kubernetes. -2. `acme-proxy` presents cryptographic challenges to verify domain ownership -3. Once validation succeeds, `acme-proxy` forwards the certificate signing request to your external CA using External Account Binding (EAB) -4. The external CA signs the certificate -5. `acme-proxy` retrieves the certificate bundle and returns it to your server - -![sequence diagram](docs/sequence.png) - ## Quick Start ```sh @@ -118,7 +114,6 @@ The most important parts of the config are - "account_email": "", "eab_kid": "", "eab_hmac_key": "", - "certlifetime": 30, "metrics": { "enabled": true, "port": 9234, diff --git a/docs/assets/highlevel-flow.png b/docs/assets/highlevel-flow.png new file mode 100644 index 0000000..6528c56 Binary files /dev/null and b/docs/assets/highlevel-flow.png differ diff --git a/docs/content/examples.md b/docs/content/examples.md deleted file mode 100644 index 816dd8f..0000000 --- a/docs/content/examples.md +++ /dev/null @@ -1,5 +0,0 @@ -+++ -title = 'Examples' -weight = 50 -BookToC = true -+++ diff --git a/docs/content/troubleshoot.md b/docs/content/troubleshoot.md new file mode 100644 index 0000000..d111324 --- /dev/null +++ b/docs/content/troubleshoot.md @@ -0,0 +1,5 @@ ++++ +title = 'Troubleshoot' +weight = 20 +BookToC = true ++++ diff --git a/docs/public/categories/index.html b/docs/public/categories/index.html index b4b6753..ccbe32c 100644 --- a/docs/public/categories/index.html +++ b/docs/public/categories/index.html @@ -136,6 +136,8 @@

+ +
  • @@ -165,8 +167,6 @@

    - - diff --git a/docs/public/client/index.html b/docs/public/client/index.html index 73dddc3..3fb58fa 100644 --- a/docs/public/client/index.html +++ b/docs/public/client/index.html @@ -22,12 +22,14 @@ Table of Contents# Installing ACME Clients Account Registration Configuring Auto-Renewal via Systemd Log Management Installing ACME Clients# Certbot# Note: Certbot’s actively maintained distribution is via Snap. The .deb packages available in apt repositories are no longer maintained by the Certbot project and ship outdated versions."> + + ACME Clients | ACME Proxy @@ -145,6 +147,8 @@

    + +
  • @@ -174,8 +178,6 @@

    - - @@ -478,6 +480,10 @@

    Log Management#
    diff --git a/docs/public/firewall/index.html b/docs/public/firewall/index.html index 78459fd..6e8e1f2 100644 --- a/docs/public/firewall/index.html +++ b/docs/public/firewall/index.html @@ -16,9 +16,11 @@ + + Port Requirements | ACME Proxy @@ -135,6 +137,8 @@

    + +
  • @@ -164,8 +168,6 @@

    - - @@ -224,6 +226,10 @@

    Port Requirements

    diff --git a/docs/public/icons/calendar.svg b/docs/public/icons/calendar.svg new file mode 100644 index 0000000..6e2a8d5 --- /dev/null +++ b/docs/public/icons/calendar.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/index.html b/docs/public/index.html index 53bfd8b..16b35c2 100644 --- a/docs/public/index.html +++ b/docs/public/index.html @@ -29,6 +29,7 @@ + ACME Proxy | ACME Proxy @@ -147,6 +148,8 @@

    + +
  • @@ -176,8 +179,6 @@

    - - @@ -266,6 +267,10 @@

    ACME Proxy

    diff --git a/docs/public/index.xml b/docs/public/index.xml index b1c7018..78e2e89 100644 --- a/docs/public/index.xml +++ b/docs/public/index.xml @@ -21,6 +21,13 @@ http://localhost:1313/install/ <h1 id="install">Install<a class="anchor" href="#install">#</a></h1> <p>Three methods are available. The install script is recommended for most deployments.</p> <table> <thead> <tr> <th>Method</th> <th>Best for</th> </tr> </thead> <tbody> <tr> <td><a href="#install-script-recommended">Install script</a></td> <td>Standard Linux servers, systemd environments</td> </tr> <tr> <td><a href="#pre-built-binary">Pre-built binary</a></td> <td>Environments where curl-pipe-to-shell is prohibited</td> </tr> <tr> <td><a href="#build-from-source">Build from source</a></td> <td>Development, or architectures not covered by releases</td> </tr> <tr> <td><a href="#docker">Docker</a></td> <td>Container-based deployments</td> </tr> </tbody> </table> <hr> <h2 id="install-script-recommended">Install Script (Recommended)<a class="anchor" href="#install-script-recommended">#</a></h2> <p>The install script downloads the appropriate release binary, creates a dedicated service user, installs a <code>ca.json</code> template, and registers a hardened <code>systemd</code> service unit.</p> + + Troubleshoot + http://localhost:1313/troubleshoot/ + Mon, 01 Jan 0001 00:00:00 +0000 + http://localhost:1313/troubleshoot/ + + User Guide http://localhost:1313/user/ @@ -35,13 +42,6 @@ http://localhost:1313/client/ <h1 id="acme-clients">ACME Clients<a class="anchor" href="#acme-clients">#</a></h1> <p>This guide covers installation and system-level configuration of ACME clients for use with acme-proxy. It is intended for system administrators deploying certificate automation on behalf of end users.</p> <p>For certificate issuance commands and per-scenario usage, see <a href="http://localhost:1313/user/">user.md</a>.</p> <hr> <h2 id="table-of-contents">Table of Contents<a class="anchor" href="#table-of-contents">#</a></h2> <ul> <li><a href="#installing-acme-clients">Installing ACME Clients</a></li> <li><a href="#account-registration">Account Registration</a></li> <li><a href="#configuring-auto-renewal-via-systemd">Configuring Auto-Renewal via Systemd</a></li> <li><a href="#log-management">Log Management</a></li> </ul> <hr> <h2 id="installing-acme-clients">Installing ACME Clients<a class="anchor" href="#installing-acme-clients">#</a></h2> <h3 id="certbot">Certbot<a class="anchor" href="#certbot">#</a></h3> <blockquote class='book-hint '> <p><strong>Note:</strong> Certbot&rsquo;s actively maintained distribution is via Snap. The <code>.deb</code> packages available in apt repositories are no longer maintained by the Certbot project and ship outdated versions.</p> - - Examples - http://localhost:1313/examples/ - Mon, 01 Jan 0001 00:00:00 +0000 - http://localhost:1313/examples/ - - Port Requirements http://localhost:1313/firewall/ diff --git a/docs/public/install/index.html b/docs/public/install/index.html index cfa5435..49d7161 100644 --- a/docs/public/install/index.html +++ b/docs/public/install/index.html @@ -20,11 +20,13 @@ Method Best for Install script Standard Linux servers, systemd environments Pre-built binary Environments where curl-pipe-to-shell is prohibited Build from source Development, or architectures not covered by releases Docker Container-based deployments Install Script (Recommended)# The install script downloads the appropriate release binary, creates a dedicated service user, installs a ca.json template, and registers a hardened systemd service unit."> + + Install | ACME Proxy @@ -142,6 +144,8 @@

    + +
  • @@ -171,8 +175,6 @@

    - - @@ -592,6 +594,10 @@

    Verify#

    diff --git a/docs/public/quickstart/index.html b/docs/public/quickstart/index.html index 0e446b3..eeaad7e 100644 --- a/docs/public/quickstart/index.html +++ b/docs/public/quickstart/index.html @@ -24,6 +24,7 @@ Installs the step-ca binary to /opt/acme-proxy/ Writes a ca.json config template to /opt/acme-proxy/ca.json Creates a dedicated acme-proxy service user Registers and enables an acme-proxy.service systemd unit The service is enabled but not started — configure ca.json first."> + @@ -31,6 +32,7 @@ For production deployments with custom install paths, build-from-source, or Docker, see install.md. Step 1 — Install# curl -fsSL https://raw.githubusercontent.com/esnet/acme-proxy/main/install.sh | sudo shThe script: Installs the step-ca binary to /opt/acme-proxy/ Writes a ca.json config template to /opt/acme-proxy/ca.json Creates a dedicated acme-proxy service user Registers and enables an acme-proxy.service systemd unit The service is enabled but not started — configure ca.json first."> + Quickstart | ACME Proxy @@ -148,6 +150,8 @@

    + +
  • @@ -177,8 +181,6 @@

    - - @@ -396,6 +398,10 @@

    Next Steps#

    diff --git a/docs/public/sitemap.xml b/docs/public/sitemap.xml index d4fdfdc..dc98a7a 100644 --- a/docs/public/sitemap.xml +++ b/docs/public/sitemap.xml @@ -3,18 +3,24 @@ xmlns:xhtml="http://www.w3.org/1999/xhtml"> http://localhost:1313/quickstart/ + 2026-04-12T20:08:41-05:00 http://localhost:1313/install/ + 2026-04-12T20:08:41-05:00 + + http://localhost:1313/troubleshoot/ http://localhost:1313/user/ + 2026-04-12T20:08:41-05:00 http://localhost:1313/client/ - - http://localhost:1313/examples/ + 2026-04-12T20:08:41-05:00 http://localhost:1313/firewall/ + 2026-04-12T20:08:41-05:00 http://localhost:1313/ + 2026-04-12T20:08:41-05:00 http://localhost:1313/categories/ diff --git a/docs/public/sw.js b/docs/public/sw.js index 54c4d29..7983406 100644 --- a/docs/public/sw.js +++ b/docs/public/sw.js @@ -3,9 +3,9 @@ const pages = [ "/quickstart/", "/install/", + "/troubleshoot/", "/user/", "/client/", - "/examples/", "/firewall/", "/", "/categories/", diff --git a/docs/public/tags/index.html b/docs/public/tags/index.html index 9e9687d..75a6b3d 100644 --- a/docs/public/tags/index.html +++ b/docs/public/tags/index.html @@ -136,6 +136,8 @@

    + +
  • @@ -165,8 +167,6 @@

    - - diff --git a/docs/public/troubleshoot/index.html b/docs/public/troubleshoot/index.html new file mode 100644 index 0000000..638d95e --- /dev/null +++ b/docs/public/troubleshoot/index.html @@ -0,0 +1,315 @@ + + + + + + + + + + + + + + + + + + + +Troubleshoot | ACME Proxy + + + + + + + + + + + + + + + + + + + +
    + + + + +
    + + + + +
    + + + +
    + +
    + +
    + +
    + + + +
    + + + + + + + + + + + + + + + + + + + + + + + + +
    + + +
    + + + + +
    + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/public/user/index.html b/docs/public/user/index.html index 4e1f164..ed40a13 100644 --- a/docs/public/user/index.html +++ b/docs/public/user/index.html @@ -24,6 +24,7 @@ Table of Contents# 1. NGINX on Linux VM / Baremetal 2. Apache on Linux VM / Baremetal 3. Standalone Mode 4. Docker and Docker Compose 5. Kubernetes (cert-manager) Prerequisites# The ACME client must be installed and an account registered with acme-proxy before running any commands in this guide. See admin.md for installation instructions and systemd renewal timer setup. Port 80 must be reachable from the acme-proxy server (used for HTTP-01 challenge validation). Your domain’s DNS must resolve to the host where the ACME client runs. Replace the following placeholders throughout this guide: acme-proxy.example.com — your acme-proxy hostname myserver.example.com — the domain you want a certificate for admin@example.com — your contact email 1. NGINX on Linux VM / Baremetal# 1a. acme.sh# Register and issue a certificate (single domain):"> + @@ -31,6 +32,7 @@ ACME directory URL: https://acme-proxy.example.com/acme/acme/directoryReplace acme-proxy.example.com with your organization’s actual acme-proxy hostname. Table of Contents# 1. NGINX on Linux VM / Baremetal 2. Apache on Linux VM / Baremetal 3. Standalone Mode 4. Docker and Docker Compose 5. Kubernetes (cert-manager) Prerequisites# The ACME client must be installed and an account registered with acme-proxy before running any commands in this guide. See admin.md for installation instructions and systemd renewal timer setup. Port 80 must be reachable from the acme-proxy server (used for HTTP-01 challenge validation). Your domain’s DNS must resolve to the host where the ACME client runs. Replace the following placeholders throughout this guide: acme-proxy.example.com — your acme-proxy hostname myserver.example.com — the domain you want a certificate for admin@example.com — your contact email 1. NGINX on Linux VM / Baremetal# 1a. acme.sh# Register and issue a certificate (single domain):"> + User Guide | ACME Proxy @@ -148,6 +150,8 @@

    + +
  • @@ -177,8 +181,6 @@

    - - @@ -1038,6 +1040,10 @@

    Troubleshooting