Skip to content
Weik.ioDocs
2026.2
Try Weik.io

Certificates

Weik.io 2026.2

Weik.io obtains and renews the certificate of every hub name and gateway hostname from Let's Encrypt or another certificate authority, such as your own or the platform's.

On this page

The hub publishes one port, 443. Its terminator terminates TLS for the hub’s two names, which are the admin UI’s address and the published leaf address. It passes the connections for every other name unopened to the API gateway. The gateway terminates TLS for each gateway hostname with that gateway’s certificate.

The terminator and the gateway accept only TLS 1.2 and 1.3, and on TLS 1.2 only the AES-GCM and ChaCha20 suites. Current browsers and HTTP libraries connect, but a client that supports only the older CBC suites, such as Safari 8, can’t.

Which source signs a name#

The platform obtains and renews the certificate of every gateway hostname. Each name is signed by the first source that fits it, in this order:

  1. A name whose DNS records point at the hub is signed by Let’s Encrypt, after the platform proves the name over TLS on port 443.
  2. A name your own certificate authority covers, added with weikio certificates authority add, is signed by that authority.
  3. A name in a zone that a DNS connection writes to is proved to Let’s Encrypt through DNS, wildcards included. The zone must be visible in public DNS.
  4. Any other name, such as an .internal one or a name on an internal network with no DNS connection, is signed by the platform’s own authority.

A public name that points elsewhere and has no DNS connection has no certificate yet. The gateway’s reply shows where the name points.

A certificate you upload on a gateway is served in place of the platform’s for the names it covers:

Terminal
$ weikio gateway set partner --server-certificate partner=chain.pem,key.pem

Only a gateway created with --certificate-source uploaded needs one.

The hub’s own names#

The platform obtains the certificates of the hub’s two names from Let’s Encrypt and renews them. The terminator loads each new certificate without a restart.

The first certificate is issued about a minute after the start, once the names’ DNS records point at the hub. Until then, the hub serves a temporary self-signed certificate, so browsers warn on the admin UI’s address. If a name still has no certificate, Settings › Platform › Installation shows why.

You set how the platform obtains certificates with flags of the first init:

Flag What it does
--certificates uploaded Turns the platform’s certificates off
--certificate-authority Gives an ACME directory other than Let’s Encrypt’s
--certificate-contact Gives the address the authority writes to
--public-address Gives an address that callers reach port 443 on

Give --public-address when the admin UI’s name resolves to addresses other than the server’s own, and repeat it for each address. A platform administrator can change these settings later on Settings › Platform › Installation.

The names are fixed at install. To move an installation to new names, back it up and restore it in a new home, which you start for the first time with the new names.

Use your own certificate#

Upload a certificate from your own certificate authority, or the origin certificate of a CDN in front of the hub, once on Settings › Platform › Installation. The platform then serves it in place of its own.

If the admin UI can’t be reached without it, for example behind a CDN that doesn’t accept the temporary certificate, give it to the first init instead. init accepts only files under the home, so copy them there first:

Terminal
$ install -d -o 1654 -g 1654 -m 0700 /opt/weikio/import
$ install -o 1654 -g 1654 -m 0600 hub.crt hub.key /opt/weikio/import/

In hub.crt, the server’s certificate comes first, then the rest of the chain. One certificate can cover both of the hub’s names.

The first start’s docker run then ends in init ... --hub-certificate company=/opt/weikio/import/hub.crt,/opt/weikio/import/hub.key. After the first start, delete /opt/weikio/import, because the platform keeps its own encrypted copy of the certificate.

You renew such a certificate by uploading the next one. The platform warns 30 days and 7 days before it expires.

If your own authority signed the certificate, give doctor the authority’s certificate so that it checks the public address against that authority:

Terminal
$ docker compose run --rm -e SSL_CERT_FILE=/etc/weikio-ca.crt -v /path/to/ca.crt:/etc/weikio-ca.crt:ro infra weikio-backend doctor

Agents trust only the authorities their host’s system trusts. To have them trust your authority, add --leaf-ca-file /opt/weikio/leaf-ca.crt to the first init line. Every agent’s bundle then has that authority’s certificate as hub-ca.crt.

Prove names through DNS#

Use a DNS connection for a name that doesn’t point at the hub, such as one proxied by a CDN or one on an internal network. The platform proves the name to Let’s Encrypt with a TXT record that it writes in the name’s zone.

For each zone, a platform administrator adds a DNS connection whose credential may write records there. For Cloudflare, that’s a token with Zone Read and DNS Write on that one zone:

Terminal
$ weikio platform secret set cf-token
$ weikio certificates dns add cf --provider cloudflare --zone acme.example --secret cf-token

The command checks the connection with a probe record, which it looks up on the zone’s public name servers and then removes. It prints the result, such as DNS connection cf added (public view public).

Other providers work the same way with their own --provider value and options:

  • Hetzner
  • Azure DNS
  • RFC 2136 servers

To have the hub’s names get their first certificate before anyone signs in, give the first init a connection with --dns-provider cloudflare --dns-zone acme.example --dns-token-file /opt/weikio/import/cf.token.

For the narrowest credential, use a zone that has nothing else in it, such as challenges.acme.example:

  1. Point the challenge name of each of your names at that zone with a CNAME record, such as _acme-challenge.api.acme.example. CNAME api.acme.example.challenges.acme.example.
  2. Give the platform the token of challenges.acme.example only.

The platform follows the CNAME and writes its records in that zone. Let’s Encrypt follows the same CNAME when it checks the name.

Your own ACME authority#

Add a certificate authority of yours that speaks ACME to have it sign the names under the suffixes you give it:

Terminal
$ weikio certificates authority add corp --acme https://ca.acme.example/acme/directory --names corp.example --trust ca.pem
You see
certificate authority corp added (signs corp.example)

Some authorities need more flags:

Flag What it does
--eab-key-id Gives the key ID of the external account binding that the authority issued to you
--eab-secret Gives the name of a platform secret that contains the account binding’s key
--orders site Lets a site gateway order from an authority that only its host reaches

The platform’s own authority#

The first start creates a certificate authority for the installation. It signs the names that no public authority signs, such as .internal ones. It also signs the client certificates a gateway presents to an upstream.

A machine that trusts this authority trusts every name it signs. To install the authority’s certificate on a machine, get it with weikio platform authority get.

To limit the authority to names under certain suffixes, give --authority-names corp.example,factory.local to the first init. The limit is fixed at the first start, so choose the suffixes before it.

For a hub with no public DNS, --hub-names-authority platform on the first init has this authority sign the hub’s names instead of Let’s Encrypt. Every agent’s bundle then has the authority’s certificate.

See and renew certificates#

Terminal
$ weikio get certificates

The list has one row for each certificate the platform manages:

  • The certificates of the hub’s names
  • The certificate of each gateway hostname
  • The certificates of a site gateway’s hostnames
  • The client certificates the gateway presents to upstreams
  • The platform’s root certificate

The list’s SOURCE column shows who signed each certificate and how, such as Let's Encrypt through TLS on port 443 or the platform's authority. Settings › Certificates shows the same list.

The platform renews certificates automatically. A certificate whose request keeps failing, or that nears its expiry, appears in the problem list.

To replace a certificate before its renewal, ask for it again:

Terminal
$ weikio certificates renew api.acme.example

A public authority issues only a few certificates a week for one exact set of names, so a renewal fails after 5 certificates for the same names in 7 days. Its error shows when you can ask for the name again.

Sign in to the live demo

Sign in with the shared viewer account. It can open every screen of the example projects but can't change anything.

E-mail
viewer@demo.weik.io
Password
try-weikio-live-demo
Open the live demo