HTTPS and SSL Certificates
When Xylok starts, it loads whatever PEM-format certificate and private key file are in /opt/xylok/certs. These files must be called cert.crt and key.key, for the certificate and private key respectively. If desired, these files can be replaced by your own certificates. After replacing these certificates, restart Xylok to apply.
If there is no existing cert.crt and key.key when it starts, Xylok generates HTTPS server certificates via a self-signed CA. It automatically generates these whenever a new domain is used to access the server, so there is no longer a need to configure XYLOK_HOST for this purpose.
The use of a separate CA allows for easier trusting of the Xylok certificates. To do so:
- Set a domain name entry for the Xylok host a. If you have a local DNS server, use that b. Otherwise, edit the system you’re accessing Xylok from’s host file. The exact details vary between Windows and Linux.
- Download your local installation’s CA certificate: a. Go to your installation’s /docs/ folder. This might be https://xylok.local/docs/ b. Click the “Xylok Certificate Authority certificate” link on that page
- Add CA certificate to the root trust store of your browser. Details vary by browser and OS:
- Open a new tab in your browser and visit your Xylok domain again. This time it should appear as trusted.
You are free to replace the certificates with custom certs if needed. To do so:
- Remove all files in
/opt/xylok/certs - Place new certificate in PEM format at
/opt/xylok/certs/cert.crt - Place new private key in PEM format at
/opt/xylok/certs/key.key - Restart Xylok:
systemctl restart xylok
ACME certificate generation (i.e. Let’s Encrypt) can be enabled to allow the Xylok server to generate fully-trusted certificates. To do so:
- Set
ACME_SERVER. You can supply a fully-qualified URL to support any ACME server, but the following nicknames are recognized for convenience:le-production: Let’s Encrypt production serverle-staging: Let’s Encrypt testing serverzerossl-production: ZeroSSL’s production server
- Set
ACME_EMAILto register with your company/personal email. - Point a DNS record to the Xylok server. As a security measure, this domain must include the word “xylok” or the server will refuse to generate an automatic certificate.
- Stop xylok:
systemctl stop xylok - Clear any existing certificate cache ON THE SERVER:
rm -rf /var/lib/xylok/home/.local/share/certmagic - Start xylok:
systemctl start xylok
If you change settings at any point, make sure you clear the existing certificate cache (step 5 above) or the server will continue to use the cached version.
Use of this automatic certificate support constitutes agreement with your chosen the ACME server’s subscriber agreement. For Let’s Encrypt, it can currently be found on their website.