Deploy static web content with Nginx

This example uses Nginx, one of the most popular web servers. Nginx can be used with Unikraft / Unikraft Cloud to serve static web content.

To run this example, follow these steps:

Install the kraft CLI tool and a container runtime engine, e.g. Docker.
Clone the examples repository and cd into the examples/nginx/ directory:

git clone https://github.com/kraftcloud/examples
cd 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 token
export UKC_TOKEN=token
# Set metro to Frankfurt, DE
export UKC_METRO=fra0

When done, invoke the following command to deploy this application on Unikraft Cloud:

kraft cloud deploy -p 443:8080 .

The output shows the instance URL and other details:

[●] Deployed successfully!
 │
 ├────────── name: nginx-67zbu
 ├────────── uuid: 8a8bc1b9-0af6-420e-a426-190dc2da9eaa
 ├───────── state: running
 ├─────────── url: https://nameless-fog-0tvh1uov.fra0.kraft.host
 ├───────── image: sha256:f51ecc121c9ca34abb88a2bc6a69765501304f7893f7e85af15fbec3dc86e2bd
 ├───── boot time: 11.13ms
 ├──────── memory: 128 MiB
 ├─────── service: nameless-fog-0tvh1uov
 ├── private fqdn: nginx-67zbu.internal
 ├──── private ip: 172.16.3.3
 └────────── args: /usr/bin/nginx -c /etc/nginx/nginx.conf

In this case, the instance name is nginx-67zbu and the URL is https://nameless-fog-0tvh1uov.fra0.kraft.host. They are different for each run.

Use curl to query the Unikraft Cloud instance of Nginx.

curl https://nameless-fog-0tvh1uov.fra0.kraft.host

<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
[...]

At any point in time, you can list information about the instance:

kraft cloud instance list

NAME                           FQDN                                      STATE    CREATED AT     IMAGE                               MEMORY   ARGS                                     BOOT TIME
nginx-67zbu                    nameless-fog-0tvh1uov.fra0.kraft.host    running  5 minutes ago  nginx@sha256:f51ecc121c9ca34abb...  128 MiB  /usr/bin/nginx -c /etc/nginx/nginx.conf  11129us

When done, you can remove the instance:

kraft cloud instance remove nameless-fog-0tvh1uov.fra0.kraft.host

Customize your Application

To customize the Nginx application, update the files in the repository, listed below:

Kraftfile: the Unikraft Cloud specification
rootfs/wwwroot/index.html: the index page of the content served
rootfs/conf/nginx.conf: the Nginx configuration file

spec: v0.6

runtime: nginx:latest

rootfs: ./rootfs

<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
    body {
        width: 35em;
        margin: 0 auto;
        font-family: Tahoma, Verdana, Arial, sans-serif;
    }
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.</p>

<p>For online documentation and support please refer to
<a href="http://nginx.org/">nginx.org</a>.<br/>
Commercial support is available at
<a href="http://nginx.com/">nginx.com</a>.</p>

<p><em>Thank you for using nginx.</em></p>
</body>
</html>

worker_processes  1;
daemon            off;
master_process    off;
user root root;

events {
  worker_connections  64;
}

http {
  include mime.types;
  default_type application/octet-stream;

  open_file_cache           max=10000 inactive=30s;
  open_file_cache_min_uses  2;
  open_file_cache_errors    on;

  error_log stderr error;
  access_log off;

  keepalive_timeout     10s;
  keepalive_requests    10000;
  send_timeout          10s;

  server {
    listen              8080;
    server_name         localhost;
    root                /wwwroot;
    index               index.html;
  }
}

Update the contents of the rootfs/wwwroot/ directory to serve different static web content. For example, you could change the contents of rootfs/wwwroot/index.html to:

<!DOCTYPE html>
<html>
<head>
<title>Hello</title>
</head>
<body>
<h2>Hello, World!</h2>
</body>
</html>

After re-deploying the Nginx image on Unikraft Cloud, using curl or a browser to query it will present the new page contents.

The static web content located in the rootfs/wwwroot/ can of course be generated offline by tools like Jekyll or Hugo.

If required, you can also customize the configuration of Nginx in rootfs/conf/nginx.conf. You can set a new webroot (different than wwwroot), or a different internal port, or a different index page, etc.

Learn More

Use the --help option for detailed information on using Unikraft Cloud:

kraft cloud --help

Or visit the CLI Reference.