App Connectors - CertForge

App Connectors automate certificate issuance and renewal for applications running on the same host as the certforge-connector agent. The connector generates the private key and CSR locally, submits the CSR to CertForge for issuance through your configured CA and Domain Trust Policy, writes the signed cert and key to the paths you specify, then runs a reload command so the application picks up the new certificate — all without manual steps or cron jobs.

[CertForge cloud] ←── poll every 30s ──── [certforge-connector]
                                                    │
                                         writes cert + key files
                                                    │
                                     [nginx / apache / app on this host]

Prerequisites

certforge-connector v0.3.3 or later installed and enrolled — see certforge-connector
A Domain Trust Policy covering the domain(s) you want to manage — see Domain Trust Profiles
The application process running as, or readable by, a user the connector can write files as (usually root when the connector runs as root)

Step 1 — Register the application in CertForge

Go to Integrations → App Connectors in CertForge.
Click + Add Application.
Fill in the fields:

Field	Example	Description
Name	`nginx-prod`	Friendly label shown in the UI
Connector Agent	`hq-connector`	The enrolled agent that will manage this app
Domain (CN)	`api.example.com`	Primary domain for the certificate
SANs	`www.api.example.com`	Additional Subject Alternative Names (comma-separated; optional)
Trust Profile	`LetsEncrypt-prod`	Domain Trust Policy governing issuance
Cert Path	`/etc/nginx/ssl/cert.pem`	Where to write the full cert bundle (leaf + chain)
Key Path	`/etc/nginx/ssl/key.pem`	Where to write the private key
Chain Path	`/etc/nginx/ssl/chain.pem`	Intermediates only, without the leaf cert (optional — useful for apps that configure the CA chain separately)
Reload Command	`nginx -s reload`	Shell command to run after cert delivery

Click Save + Request Cert to save the app and immediately queue an issuance job. Use Save Only if you want to configure the app without triggering issuance yet (for example, to set up the file paths before the cert is needed).

No changes to certforge-connector.yaml are required — all app configuration is stored in CertForge and delivered to the connector with each job.

Step 2 — Approve the request (if required)

If the Domain Trust Policy requires human approval, the job enters Pending Approval and appears in the Approvals queue. An authorized approver must approve it before issuance proceeds. If the DTP is set to auto-approve, issuance starts immediately.

Step 3 — Verify delivery

On the next connector poll (within poll_interval, default 30 s), the connector:

Picks up the cert_ready job
Writes the private key to key_path (mode 0600)
Writes the full cert bundle (leaf + chain) to cert_path (mode 0644)
Writes the chain only to chain_path if configured
Runs the reload command
Marks the job done — the app’s status updates to Active with the cert expiry date

Verify the cert is live:

openssl s_client -connect localhost:443 -servername api.example.com \
  </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer -dates

The connector log will show each step:

[app-connector] job abc123 (nginx-prod): generating RSA 2048 key + CSR for api.example.com
[app-connector] job abc123: private key written to /etc/nginx/ssl/key.pem
[app-connector] job abc123 (nginx-prod): CSR submitted — status: pending_approval
[app-connector] job abc123 (nginx-prod): cert_ready — delivering to /etc/nginx/ssl/cert.pem
[app-connector] job abc123: cert bundle written to /etc/nginx/ssl/cert.pem
[app-connector] job abc123: running reload: nginx -s reload
[app-connector] job abc123: reload complete
[app-connector] job abc123 (nginx-prod): complete — cert delivered and service reloaded

Application recipes

The + Add App form includes a Use a template dropdown that pre-fills the paths and reload command for common applications. Templates are a starting point — adjust paths to match your actual configuration before saving. The connector runs reload commands via sh -c, so pipes, &&, and environment variable substitution all work. If the command exits non-zero, the job is marked Failed in CertForge and an alert fires if configured.

nginx

Field	Value
Cert Path	`/etc/nginx/ssl/cert.pem`
Key Path	`/etc/nginx/ssl/key.pem`
Chain Path	`/etc/nginx/ssl/chain.pem` (optional)
Reload Command	`nginx -s reload`

cert.pem receives the full bundle (leaf + intermediates + root), which is what ssl_certificate expects. chain.pem receives the intermediates-only chain for apps that configure ssl_trusted_certificate separately. Adjust the directory to match your site’s ssl_certificate directive — a common alternative is /etc/nginx/certs/ or /etc/ssl/nginx/.

Apache (Debian / Ubuntu)

Field	Value
Cert Path	`/etc/apache2/ssl/cert.pem`
Key Path	`/etc/apache2/ssl/key.pem`
Chain Path	`/etc/apache2/ssl/chain.pem` (optional)
Reload Command	`systemctl reload apache2`

Point SSLCertificateFile at cert.pem and SSLCertificateKeyFile at key.pem. If using a separate chain file, set SSLCertificateChainFile to chain.pem (Apache 2.4.8+ supports the full chain in SSLCertificateFile so a separate chain file is often unnecessary).

Apache (RHEL / CentOS / AlmaLinux)

Field	Value
Cert Path	`/etc/httpd/ssl/cert.pem`
Key Path	`/etc/httpd/ssl/key.pem`
Chain Path	`/etc/httpd/ssl/chain.pem` (optional)
Reload Command	`systemctl reload httpd`

Same configuration directives as the Debian variant; only the service name (httpd vs apache2) and default config paths differ.

HAProxy

HAProxy reads the certificate and private key from a single combined file — it does not accept separate cert and key files. Use the reload command to concatenate them immediately after delivery:

Field	Value
Cert Path	`/etc/haproxy/certs/cert.pem`
Key Path	`/etc/haproxy/certs/key.pem`
Chain Path	(leave blank)
Reload Command	`cat /etc/haproxy/certs/cert.pem /etc/haproxy/certs/key.pem > /etc/haproxy/certs/bundle.pem && systemctl reload haproxy`

Point the bind line at bundle.pem:

bind *:443 ssl crt /etc/haproxy/certs/bundle.pem

The connector writes cert.pem and key.pem separately; the reload command concatenates them into bundle.pem before signalling HAProxy.

Postfix + Dovecot (mail server)

Both Postfix and Dovecot read the same cert and key files, so a single App Connector entry covers both. The reload command signals both services:

Field	Value
Cert Path	`/etc/ssl/mail/cert.pem`
Key Path	`/etc/ssl/mail/key.pem`
Chain Path	(leave blank — Postfix reads the full chain from cert.pem)
Reload Command	`systemctl reload postfix && systemctl reload dovecot`

In main.cf:

smtpd_tls_cert_file = /etc/ssl/mail/cert.pem
smtpd_tls_key_file  = /etc/ssl/mail/key.pem

In dovecot.conf (or conf.d/10-ssl.conf):

ssl_cert = </etc/ssl/mail/cert.pem
ssl_key  = </etc/ssl/mail/key.pem

PostgreSQL

Field	Value
Cert Path	`/etc/postgresql/ssl/server.crt`
Key Path	`/etc/postgresql/ssl/server.key`
Chain Path	(leave blank)
Reload Command	`systemctl reload postgresql`

PostgreSQL requires the key file to be owned by the postgres user and mode 0600. Run the connector as root (typical) and add an ownership step to the reload command:

chown postgres:postgres /etc/postgresql/ssl/server.key && chmod 600 /etc/postgresql/ssl/server.key && systemctl reload postgresql

In postgresql.conf:

ssl = on
ssl_cert_file = '/etc/postgresql/ssl/server.crt'
ssl_key_file  = '/etc/postgresql/ssl/server.key'

MySQL / MariaDB

Field	Value
Cert Path	`/etc/mysql/ssl/server.crt`
Key Path	`/etc/mysql/ssl/server.key`
Chain Path	`/etc/mysql/ssl/ca.pem` (optional — for client cert validation)
Reload Command	`systemctl restart mysql`

MySQL requires a restart (not reload) to pick up new TLS certificates. In my.cnf:

[mysqld]
ssl_cert = /etc/mysql/ssl/server.crt
ssl_key  = /etc/mysql/ssl/server.key

For MariaDB, use systemctl restart mariadb instead.

Envoy

Field	Value
Cert Path	`/etc/envoy/certs/cert.pem`
Key Path	`/etc/envoy/certs/key.pem`
Chain Path	(leave blank)
Reload Command	`kill -HUP $(cat /var/run/envoy.pid)`

Alternatively, if running under systemd: systemctl reload envoy.

Node.js / custom applications

For a Node.js HTTPS server or any custom application that reads cert files directly, use paths that match your application’s configuration and a reload command appropriate for how your process manager restarts the app:

Field	Value
Cert Path	`/etc/myapp/ssl/cert.pem`
Key Path	`/etc/myapp/ssl/key.pem`
Chain Path	(optional)
Reload Command	`systemctl restart myapp` or `pm2 restart myapp`

If the application watches for file changes and reloads automatically, the reload command can be omitted.

Managing App Connectors

From Integrations → App Connectors you can:

Action	Description
Edit	Update paths, reload command, or Trust Profile — takes effect on next renewal
Renew	Manually trigger a new issuance cycle, for example after a domain or path change
Disable / Enable	Pause cert delivery for an app without deleting it; disabled apps are excluded from connector polls
Delete	Remove the app and its associated jobs

Renewal

CertForge schedules automatic renewal based on the cert expiry date and the renewal lead configured in the Domain Trust Policy (default 30 days). When the renewal window opens, CertForge queues a new pending_csr job and the connector picks it up on its next poll — no manual steps required. To trigger early renewal at any time, click Renew on the app in the CertForge UI.

How the private key is handled

The connector generates the RSA private key on the local host and writes it to key_path before submitting the CSR. This means:

The key never leaves the host
If the connector restarts between CSR submission and cert delivery, the key is already in place
When using an ACME CA (Let’s Encrypt, ZeroSSL), the CA generates its own key internally and returns it with the certificate — CertForge forwards this key to the connector, which writes it to key_path, ensuring the key on disk always matches the issued certificate

Troubleshooting

Job stuck in pending_csr — the connector isn’t running or can’t reach CertForge. Check journalctl -u certforge-connector and verify the enrollment credentials are valid. Reload command failed — the command exited non-zero. The error output is recorded in the job’s Error field in CertForge. Common causes: wrong path, missing permissions, or the application isn’t running. Fix the command under Edit, then click Renew. Key values mismatch on reload — if you see SSL_CTX_use_PrivateKey failed: key values mismatch in your application logs, the key on disk doesn’t match the cert. This can happen if the cert was written by a different process after the connector wrote the key. Click Renew to start a fresh issuance cycle — the connector will generate a new key and matching cert. App shows error status — check the Last Error field on the App Connectors page for the failure message, and the connector log for more context.

​Prerequisites

​Step 1 — Register the application in CertForge

​Step 2 — Approve the request (if required)

​Step 3 — Verify delivery

​Application recipes

​nginx

​Apache (Debian / Ubuntu)

​Apache (RHEL / CentOS / AlmaLinux)

​HAProxy

​Postfix + Dovecot (mail server)

​PostgreSQL

​MySQL / MariaDB

​Envoy

​Node.js / custom applications

​Managing App Connectors

​Renewal

​How the private key is handled

​Troubleshooting