Home / Alt manpages / hugo-server-trust(1)

  • hugo-server-trust(1)
  • User command
  • linux

Trust Hugo's Local HTTPS Certificate on Linux

Testing a feature that only breaks over HTTPS means teaching your machine to trust Hugo's own certificate authority first. hugo server trust installs that local CA into your trust stores so hugo server --tlsAuto stops throwing certificate warnings. This applies to the Hugo 0.123.7 package installed on this machine, and takes about five minutes.

The route

Jump straight to the step you need, or tick off Done means at the end.

  • You need: Hugo, an existing Hugo site, and an account that can approve the privileged trust-store operation.
  • Warning: this changes local certificate trust. Do not run it on a shared or production host without understanding who inherits that trust.

1. Check the installed command

Start in the root of the Hugo site you want to serve. The trust subcommand still loads site configuration, so running it from an arbitrary directory can fail with a message about a missing config file. If the site is elsewhere, pass its path with --source.

$ hugo version
hugo v0.123.7+extended linux/amd64 BuildDate=2026-03-17T19:51:14Z VendorInfo=ubuntu:0.123.7-1ubuntu0.3+esm2
$ hugo server trust --help
Install the local CA in the system trust store.

Checkpoint

The help text shows hugo server trust [flags] [args] and the --uninstall option. This is a subcommand of hugo; there is normally no separate hugo-server-trust executable to invoke.

2. Install the local CA

$ hugo server trust

Hugo delegates this to the mkcert library it uses for locally trusted TLS certificates. On a normal unprivileged account, the underlying installation may ask for sudo credentials: read the prompt before approving it. This installs a development CA into trust stores; it does not obtain a public certificate and it does not secure a remote website.

The exact status messages depend on the platform and available tools. A successful run reports the local CA installed in the system trust store, and may separately report browser or Java stores, or warn when an optional store cannot be updated. A warning about one unavailable browser helper does not mean every browser trusts the CA.

Checkpoint

If you see Unable to locate config file or config directory, change to the site directory or supply the source explicitly:

$ hugo server trust --source /path/to/your/site

3. Start HTTPS and check the result

Keep the terminal in the site root:

$ hugo server --tlsAuto

Hugo generates or reuses a certificate for the local server and normally listens on https://localhost:1313/. Leave this running. From another terminal:

$ curl --fail --silent --show-error --head https://localhost:1313/
HTTP/1.1 200 OK

The exact status and headers can vary with the site and Hugo version, so treat the successful TLS connection and a non-error response as the useful check. If curl reports an unknown issuer, first confirm the trust command completed for the same user and host: a browser may keep its own certificate database and need a restart before it notices the change.

Checkpoint

This proves trust for a local development endpoint only. It does not test a public hostname, a reverse proxy, a container, or an application with its own certificate store.

4. Know the boundary of that trust

The local CA is powerful within every store it is installed in: any software using those stores accepts certificates it signs. Keep it private to the development machine.

  • Never copy its private key to a server.
  • Never commit it to a repository.
  • Never use this arrangement to impersonate a production service. Hugo's development server is for local development, not an internet-facing deployment.

Trust is also store-specific. Installing the CA into the system store does not guarantee Firefox, Chromium-based browsers, Java, Python, Node.js, or a container image will use it. If only one client fails, check that client's own trust-store configuration rather than repeatedly rerunning the installer.

5. Remove the local CA when you are done with it

$ hugo server trust --uninstall

This removes the local CA from the stores mkcert can manage, but it does not delete the CA files themselves, and it can also need elevated privileges. Close and restart clients that cache trust decisions, then repeat the HTTPS request: it should now fail certificate verification unless that client has another reason to trust it.

Recovery

Because uninstall does not delete the CA, it is reversible: running hugo server trust again reinstalls the same local CA. If the CA itself must be retired, use the CA-management tooling documented for your installed Hugo and mkcert versions, and verify the exact CA root before removing anything. Do not delete a broad configuration directory as a shortcut.

Done means

  • hugo server trust --help identifies the command and its --uninstall option.
  • hugo server trust completes from the intended Hugo site and reports which stores it changed.
  • hugo server --tlsAuto serves the site locally over HTTPS.
  • A client using the updated store connects to https://localhost:1313/ without an unknown-issuer error.
  • You know how to run hugo server trust --uninstall once this development trust is no longer wanted.