Deploying to Custom Domains
In this guide we will show you how to deploy an app on Unikraft Cloud (UKC) and link it to a domain name you own (e.g., mydomain.com).
Configuring your External DNS Provider
Before we can launch an app, you need to ensure that you have configured things correctly with your DNS provider. There are two cases here:
- For a subdomain you own such as docs.mydomain.com, a CNAME is enough.
In this case, you can just add a
CNAME
record with your sub-domain (docs
) as the host and point the record to UKC’s metro e.g.,fra0.kraft.host
. - For an apex domain (e.g., mydomain.com), add an ALIAS, ANAME, or flattened CNAME record. Depending on your provider, leave the host field empty or enter @.
Point the record to UKC’s metro e.g.,
fra0.kraft.host
. If your DNS provider does not support ALIAS, ANAME, or flattened CNAME records, add an A record and point the record to the IP address of UKC’s metro
Launching your App
Let’s assume we want to use NGINX as our app:
git clone https://github.com/unikraft-cloud/examplescd examples/nginx
Make sure to log into Unikraft Cloud by setting your token and a metro close to you.
We use fra0
(Frankfurt, 🇩🇪) in this guide:
# Set Unikraft Cloud access tokenexport UKC_TOKEN=token# Set metro to Frankfurt, DEexport UKC_METRO=fra0
With this in place, we’ll use the kraft cloud deploy
command to create an instance of the web server and to link it to a custom name; the latter is done through the -d
flag:
kraft cloud deploy -p 443:8080 -d mydomain.com .
The resulting output of the deploy
command should be similar to:
[●] Deployed successfully! │ ├────────── name: nginx-67zbu ├────────── uuid: 269019de-f7dc-4077-9568-012ad594ca87 ├───────── state: running ├─────────── url: https://mydomain.com ├───────── image: nginx@sha256:6abb4f2ba4501068a84885d7b8b127adaf3d83c25fd43e79d5a142f6d8703c93 ├───── boot time: 11.13ms ├──────── memory: 1024 MiB ├─------ service: wispy-moon-dpg6d54i ├── private fqdn: nginx-67zbu.internal ├──── private ip: 172.16.6.5 └────────── args: /usr/bin/nginx -c /etc/nginx/nginx.conf
In case you’re curious, when issuing the -d
flag Unikraft Cloud will request a new certificate from Let’s Encrypt.
You’re all set! You can test your deployment with curl
:
curl https://mydomain.com
Custom and Wildcard Certificates
If you want to use a custom certificate instead of the auto-generated Let’s Encrypt one, you can use the create
command:
kraft cloud cert create --cn *.mydomain.com --name mydomain-cert --pkey /path/to/private.key --chain /path/to/chain.pem
The provided common name (CN) must match the one for which the certificate has been issued. As shown in the example, this can also be a wildcard domain.
To see and manage your certificates you can use the kraft cloud cert
command. For instance,
to list your certificate, run:
To see and manage your certificates you can use the kraft cloud cert
command.
For instance, to list your certificate, run:
kraft cloud cert ls
You should see output similar to:
NAME STATE COMMON NAME CREATED ATmydomain.com-sa4x9 valid mydomain.com 5 days agomydomain-cert valid *.mydomain.com 2 days ago
You can also retrieve full information about your certificate via
kraft cloud cert get mydomain.com-sa4x9
You should see output similar to:
uuid: b8160db9-7cba-4b80-9107-c4fe27529bf5 name: mydomain.com-sa4x9 state: valid common name: mydomain.com subject: CN=mydomain.com issuer: CN=R3,O=Let's Encrypt,C=US serial number: 0455BBAEC140EACBA5FEEAE6D817E73EF266 not before: 2024-03-07T18:06:11Z not after: 2024-06-05T18:06:10Z created at: 2024-03-07T19:06:04Z services: wispy-moon-dpg6d54i
Finally, if you want to remove the certificate, first make sure you (1) remove any instances from the relevant service and (2) remove the service. After that you can remove the actual certificate with:
kraft cloud cert rm mydomain.com-sa4x9
Learn More
- The
kraft cloud
CLI reference - Unikraft Cloud’s REST API reference
- Many more guides here