This tutorial will teach you how to install your Django development environment and how to set up Django in Theia.

You can follow this tutorial with the commits on slapos:django-tutorial

Create a django directory into software folder.

$ cd ~/srv/project/slapos/software/
$ mkdir django-tutorial

Create software.cfg file in django-tutorial directory.

$ cd django-tutorial
$ touch software.cfg

First, include (in buildout parlance, we say "extend") standard buildout components for SlapOS.

[buildout]
extends =
  ../../stack/slapos.cfg

Then select a python version (python3 refers to the current default for Python 3 in SlapOS).

[python]
part = python3

This actually overrides the old value for part in the [python] section defined in slapos/component/defaults.cfg.

Your code should now match the commit: Add buildout and python section in software.cfg.

The software.cfg file is a buildout profile that defines how to install a software. By the end of this tutorial, it will define how to install Django. Right now, it only defines how to install Python 3. Let's use SlapOS to compile it:

$ slapos supply ~/srv/project/slapos/software/django-tutorial/software.cfg slaprunner
$ slapos node software

The first command adds our buildout profile to the list of softwares that the SlapOS node embedded inside Theia should install.
The second command makes the node install the pending softwares in the list.
See here for more details.
The SlapOS node inside Theia actually runs slapos node software in the background automatically every minute.
Compiling Python could take a while. To make it go faster, you can run this modified command instead:

$ MAKEFLAGS=-j20 slapos node software

When it's finished, you should have this output:

[buildout]
extends = 
  ../../stack/slapos.cfg
  ../../component/macros/virtual-env.cfg

parts =
  django-env

[django-env]
<= virtual-env-base
location = ${buildout:directory}/activate
eggs = Django

[python]
part = python3

The option 'location' defines the virtual environment script's location.
Look here to learn more about this macro.

Your code should now match the commit: Install Django packages.

Now we want to recompile the buildout profile to apply the last changes.

Since we already supplied it to the node, we don't need to do it again.

However, the node doesn't know that the file has changed, so running slapos node sofware will not be enough: the node will consider that the software is already compiled and there is nothing to do. This makes sense in the normal run of things, because buildout profiles are usually never modified: it only happens when we are developing one.

In order to force the node to recompile, we can run:

$ slapos node software --all

We purposefully left a mistake in our buildout profile, so you should see this error:

Actually, you need to specify the version of the Python eggs you want to install. This it to make the buildout profile reproducible
(instead of just installing the last version of the eggs, which will change the next time the a new version is released).

[versions]
Django = 4.0.6

If you recompile with slapos node software --all, you will see another error, the Python packages require by Django:

[versions]
Django = 4.0.6
backports.zoneinfo = 0.2.1
sqlparse = 0.4.2
asgiref = 3.5.2

Note: if the python package you want to install is distributed as a wheel, it will not be considered by default. To force buildout to select it, just add ":whl" at the end of the line.
For example:

[versions]
Django = 4.0.6:whl

Now, you can recompile with:

$ slapos node software --all

No errors are expected.

Your code should now match the commit: Add versions in software.cfg.

Tip: Find Django eggs versions

[buildout]
...
allow-picked-versions = true

$ slapos node software --all

[versions]
Django = 4.0.6
backports.zoneinfo = 0.2.1
sqlparse = 0.4.2
asgiref = 3.5.2

To use Django, you should create an instance to publish the activate script path.
The macro virtual-env conveniently defines a default instance that does it for you (see here). You just have to instantiate it with SlapOS.

Request an instance with:

$ slapos request django ~/srv/project/slapos/software/django-tutorial/software.cfg
$ slapos node instance

Get the path of the activate script by

$ slapos service info django

You can copy the path of the script and activate the virtual environment with:

$ source <path>

Now you can learn how to use Django in Theia with this tutorial: How to use Django stack in Theia