Skip to main content

Local Web Server Deployment

Use this guide for nginx, Apache HTTP Server (httpd), or OpenResty installed directly on Linux or macOS. For applications in containers, use Docker Deployment.

The normal path is initialize → configure certificate paths → deploy → verify → enable the background service. You need a deployment node, its Token, and at least one issued certificate associated with it.

1. Initialize for your web server​

After installing CertOne, run:

certone init

Choose nginx, httpd, or openresty. Confirm the application executable selected by the wizard. Apache on Debian/Ubuntu commonly uses apache2ctl; other installations may use apachectl or httpd.

The wizard saves credentials and deployment commands in ~/.certone/config.yaml. It does not change your web server configuration or start a service. Leave {id} in the generated output paths: each associated certificate gets its own directory.

Choose the runtime account before deploying

The account must be able to write certificate files and reload the web server. If the application runs under your own account, use ordinary commands throughout. If it is managed by root, use the sudo command shown below for deployment and subsequent maintenance. Sudo is needed to manage that process, not to connect to CertOne. Always retain the explicit path to your original configuration. See Permissions.

2. Find the certificate and configure HTTPS​

certone check
certone doctor --network

The network check lists available certificate IDs and versions. It does not deploy certificates. If none are listed, associate an issued, unexpired certificate with this node in the platform.

For nginx or OpenResty, update the existing HTTPS site's certificate directives:

ssl_certificate     /home/deploy/.certone/certificates/cert-REPLACE/fullchain.pem;
ssl_certificate_key /home/deploy/.certone/certificates/cert-REPLACE/key.pem;

For Apache, update the existing SSL virtual host:

SSLCertificateFile "/home/deploy/.certone/certificates/cert-REPLACE/fullchain.pem"
SSLCertificateKeyFile "/home/deploy/.certone/certificates/cert-REPLACE/key.pem"

Replace /home/deploy with the runtime user's actual absolute home path and cert-REPLACE with the ID listed by the network check. For example, macOS homes commonly start with /Users/. Do not put ~ or {id} in the web server configuration. If you chose a custom output directory, use that instead.

Keep the site's domain, listening port, routing, and other settings. These directives assume HTTPS is enabled in the application. Do not manually reload until the files exist.

3. Deploy to an already running application​

For an application managed by your current account:

certone sync --once
certone status

For a root-managed application, run this from the account that created the configuration. Sudo grants permission to reload the application and write protected files; the explicit configuration path avoids switching to root's home:

sudo "$(command -v certone)" sync --once --config "$HOME/.certone/config.yaml"
sudo "$(command -v certone)" status --config "$HOME/.certone/config.yaml"

Choose the appropriate command group; do not run both. Once state and logs are root-owned, use the same privileged account for subsequent checks and maintenance. Deployment writes the certificate files, checks application configuration, and reloads the application. A failed check prevents reload and restores the previous files.

status lists completed targets, certificate versions and output paths. A stopped snapshot after a one-time synchronization is normal. Inspect the certificate served by the actual HTTPS site before enabling continuous operation.

First startup without a certificate​

If the application cannot start until its certificate files exist, keep the configuration produced by the wizard. You do not need to remove and later restore reload settings:

  1. Run certone sync --once --prepare using the runtime account and configuration path chosen above. For a root-managed application, add --prepare to the sudo deployment command above.
  2. Use the output paths shown in the logs in your web server configuration, as in step 2.
  3. Validate and start the application using its usual management tool.
  4. Run certone sync --once without --prepare to complete validation, reload and optional endpoint verification.
  5. Inspect certone status and the actual HTTPS endpoint.

Preparation only writes certificate files. It does not execute check, reload, rollback activation commands or verify, and does not report a completed deployment. It is for initial startup, not for bypassing a failing production reload. Normal file recovery can still restore interrupted writes.

For Docker, certone exec handles preparation and application startup together.

4. Keep certificates up to date​

Follow Background Services to register and start the service. Stop any foreground CertOne process first. Service installation requires administrator privileges because it changes system-service registration.

The default service runs as root on Linux/macOS. Applications managed by an ordinary user can instead run CertOne under an existing process manager with that same account.

Optional: verify the certificate served by the application​

Add verify to the file target in config.yaml:

    verify:
      address: 127.0.0.1:443
      server_name: example.com

Use the actual reachable address and HTTPS hostname. Restart CertOne after editing configuration. verified: true then confirms that its TLS check succeeded; without verify, inspect the endpoint yourself.

For custom configuration files, nginx prefixes, Apache environment requirements, and scripts, see Custom Commands. For failures, use Troubleshooting before changing permissions or deleting state.