Run a Django App
In this guide we create and deploy a Python Django web application. To run this example, follow these steps:
-
Install the
kraft
CLI tool and a container runtime engine, e.g. Docker. -
Clone the
examples
repository andcd
into theexamples/http-python3.12-django5.0/
directory:
git clone https://github.com/kraftcloud/examplescd examples/http-python3.12-django5.0/
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
When done, invoke the following command to deploy this application on Unikraft Cloud:
kraft cloud deploy -p 443:80 -M 512 .
The output shows the instance URL and other details:
[●] Deployed successfully! │ ├────────── name: http-python312-django50-vt56c ├────────── uuid: d8469447-fdf6-4caf-9fea-494218ca6f72 ├───────── state: running ├─────────── url: https://dawn-sound-n5wrkxi2.fra0.kraft.host ├───────── image: http-python312-django50@sha256:221666d414299aff54dbf10020b3d540270ee0c5907c1c6a728ca254ce8b0e50 ├───── boot time: 80.32 ms ├──────── memory: 512 MiB ├─────── service: dawn-sound-n5wrkxi2 ├── private fqdn: http-python312-django50-vt56c.internal ├──── private ip: 172.16.6.5 └────────── args: /usr/bin/python3 /app/main.py
In this case, the instance name is http-python312-django50-vt56c
and the URL is https://dawn-sound-n5wrkxi2.fra0.kraft.host
.
They are different for each run.
Use curl
to query the Unikraft Cloud instance of the Django web app server:
curl https://dawn-sound-n5wrkxi2.fra0.kraft.host
<!doctype html>
<html lang="en-us" dir="ltr"> <head> <meta charset="utf-8"> <title>The install worked successfully! Congratulations!</title> <meta name="viewport" content="width=device-width, initial-scale=1"> <style> html { line-height: 1.15; } a { color: #19865C; }[...]
Or point a browser at the URL and/or its /admin
area. The username and password are
set in the Dockerfile
(more on this file later) to unikraft/unikraft
.
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 TIMEhttp-python312-ma2i9 young-night-5fpf0jj8.fra0.kraft.host running 1 minute ago http-python312@sha256:278cb8b14f9faf9c27... 512 MiB /usr/bin/python /src/server.py 15094us
When done, you can remove the instance:
kraft cloud instance remove http-python312-django50-vt56c
Customize your Application
To customize the application, update the files in the repository, listed below:
main.py
: the entry point for the appKraftfile
: the Unikraft Cloud specificationDockerfile
: the Docker-specified application filesystem
import bjoernimport helloworld.wsgiimport osfrom werkzeug.middleware.shared_data import SharedDataMiddleware
app = helloworld.wsgi.applicationapp = SharedDataMiddleware(app, {'/static': '/app/static',})bjoern.run(app, "0.0.0.0", 80)
spec: v0.6
runtime: python:3.12
rootfs: ./Dockerfile
cmd: ["/usr/bin/python3", "/app/main.py"]
FROM python:3.12-bookworm AS base
WORKDIR /app
COPY requirements.txt /app
RUN apt update && \apt-get install -y --no-install-suggests --no-install-recommends libev-dev && \pip3 install -r requirements.txt --no-cache-dir
FROM base AS staticADD . /appRUN python3 manage.py collectstatic --noinput
FROM scratch
COPY --from=base /usr/local/lib/python3.12 /usr/local/lib/python3.12COPY --from=base /usr/lib/x86_64-linux-gnu/libev.so.4 /usr/lib/x86_64-linux-gnu/libev.so.4COPY --from=base /usr/lib/x86_64-linux-gnu/libsqlite3.so.0 /usr/lib/x86_64-linux-gnu/libsqlite3.so.0ADD manage.py main.py /app/ADD helloworld /app/helloworld/COPY --from=static /app/static /app/static
Lines in the Kraftfile
have the following roles:
-
spec: v0.6
: The currentKraftfile
specification version is0.6
. -
runtime: python:3.12
: The Unikraft runtime kernel to use is Python 3.12. -
rootfs: ./Dockerfile
: Build the application root filesystem using theDockerfile
. -
cmd: ["/usr/bin/python3", "/app/main.py"]
: Use this as the starting command of the instance.
Lines in the Dockerfile
have the following roles:
FROM scratch
: Build the filesystem from thescratch
container image, to create a base image.
The following options are available for customizing the application:
-
If only updating the implementation in the
main.py
source file, no other change is required. -
If new files are added, these have to be copied in the application filesystem, using the
COPY
command in theDockerfile
. -
If a new Python source files is added, update the
cmd
line in theKraftfile
and replaceserver.py
to run that file when creating the instance. -
More extensive changes may require expanding the
Dockerfile
with additionalDockerfile
commands. This includes the use of Python frameworks and the use ofpip
, as shown in the next section.
Using pip
pip
is a package manager for Python.
It is used to install dependencies for Python applications.
pip
uses the requirements.txt
file to list required dependencies (with versions).
The http-python3.12-flask3.0
guide details the use of pip
to deploy an application using the Flask
framework on Unikraft Cloud.
Run the command below to deploy the application on Unikraft Cloud:
kraft cloud deploy -p 443:80 -M 512 .
Differences from the Django app are also the steps required to create an pip
-based app:
-
Add the
requirements.txt
file used bypip
. -
Add framework-specific source files. In our case, this means the
server.py
file. -
Update the
Dockerfile
to:-
COPY
the local files. -
RUN
thepip3 install
command to install dependencies. -
COPY
of the resulting and required files (/usr/local/lib/pyhon3.12
andserver.py
) in the application filesystem, using thescratch
container.
-
The files are listed below:
flask>=3.0,<3.1
spec: v0.6
runtime: python:3.12
rootfs: ./Dockerfile
cmd: ["/usr/bin/python3", "/app/server.py"]
FROM python:3.12-bookworm AS base
WORKDIR /app
COPY requirements.txt /app
RUN apt update && \apt-get install -y --no-install-suggests --no-install-recommends libev-dev && \pip3 install -r requirements.txt --no-cache-dir
FROM base AS staticADD . /appRUN python3 manage.py collectstatic --noinput
FROM base AS dbADD . /appRUN python3 manage.py migrate && \DJANGO_SUPERUSER_PASSWORD=unikraft python3 manage.py createsuperuser --noinput --username unikraft --email mail@example.com
FROM scratch
COPY --from=base /usr/local/lib/python3.12 /usr/local/lib/python3.12COPY --from=base /usr/lib/x86_64-linux-gnu/libev.so.4 /usr/lib/x86_64-linux-gnu/libev.so.4COPY --from=base /usr/lib/x86_64-linux-gnu/libsqlite3.so.0 /usr/lib/x86_64-linux-gnu/libsqlite3.so.0ADD manage.py main.py /app/ADD helloworld /app/helloworld/COPY --from=static /app/static /app/staticCOPY --from=db /app/db.sqlite3 /app/db.sqlite3
The requirements.txt
file lists the flask
dependency.
The Kraftfile
is the same one used for Django.
For Dockerfile
newly added lines have the following roles:
-
FROM python:3.12-bookworm AS base
: Use the base image of thepython:3.12-bookworm
container. This provides thepip3
binary and other Python-related components. Name the current imagebase
. -
WORKDIR /app
: Use/app
as working directory. All other commands in theDockerfile
run inside this directory. -
COPY requirements.txt /app
: Copy the package configuration file to the Docker filesystem. -
RUN pip3 install ...
: Installpip
components listed inrequirements.txt
. -
COPY --from=base ...
: Copy generated Python files in the newbase
image in thescratch
-based image.
Similar actions are required for other pip3
-based applications.
See also the http-python3.12-django5.0
example.
Learn More
Use the --help
option for detailed information on using Unikraft Cloud:
kraft cloud --help
Or visit the CLI Reference.