Django development

Initialize the Django Project

Create a gitlab repo

Create a blank git project on a gitlab server that will hold the django project. It is helpful to have this git repo created prior to initializing the project, so that the django project can be created directly into the repo instead of having to initialize and link the git repo after the django project is created, which tends to be more difficult.

Start the dev environment

To start the project, we need an environment that is setup for developing django projects. It is recommended to have a Docker container specifically for this purpose. Note that we are not going to run the django project from this container. This container is only for starting up the project.

The ece-li-scheduling-docker git repo contains a Dockerfile called Dockerfile.django-dev.001 to build such an environment.

• Enter the dev environment:

  docker exec -it dev-env-1 /bin/bash

• Go to the /opt folder.

Clone the repo

Now, we are going to clone the git repo using an access token. This is assuming that the project is on a gitlab server.

• Create the access token.

  • Go to the gitlab repo web page.

  • Under Settings (left sidebar), select Access tokens.

  • In the Token name field, enter initialize project.

  • For the Expiration date field, the default value should be sufficient, as this git clone won’t be needed after the project is initialized.

  • For the Select a role dropdown, select Developer. This is to permit the clone to write to the repo.

  • It should be unnecessary to select any of the scopes.

  • Click the Create project access token button.

  • A green field will appear with the project access token hidden. Click the Copy project access token button, next to the eye (reveal) button to copy the token to the clipboard.

Open

• Clone the git repo.

  git clone https://<project access token>@<gitlab repo address>

  For example,

  git clone https://glpat-xYzCB3sMjfFYz5Q6hyH2@git.uwaterloo.ca/d24lau/ece-li-scheduling.git

  • You will be prompted to enter a password. Enter the project access token as the password.

Configure git

• Go into the project folder that was created when the repo was cloned.

• Set the user.email and user.name git parameters.

Initialize the project

• Go into the project folder that was created when the repo was cloned.

• Start the project. Be sure to enter the . at the end of the command line in order to create the project in the current folder. Otherwise, django will create a subfolder with the project name and place it one level down.

• Set the ALLOWED_HOSTS setting in the settings.py file. For example:

• Optional - add a .gitignore file to the root project directory. Add the file db.sqlite3 to this .gitignore file so that the SQLite database does not get stored in the git repo.

Push first commit

• Create new branch initialize. The project access token is not permitted to push to main branch.

• Commit the initial files created by django for the project.

• Merge the initialize branch into main branch.

Build Run-time Environment

Create a gitlab repo

Create a blank git project on a gitlab server that will hold the Dockerfiles for building the run-time container.

Create deploy key

• From the Dockerfile repo:

• Commit and push the repo.

• On the gitlab repo web page, go to Settings → Repository.

• Expand the Deploy keys section.

• Click the Add new key button.

• Enter the Title field (e.g. Run-time environment).

• Copy and paste the contents of the SSH key .pub file into the Key field.

• Depending on whether or not you wish to develop in another environment and only deploy to the run-time environment, or whether you wish to use the container to make changes to the codebase, select whether or not to grant write privileges to the deploy key.

Create Dockerfile

Add the deploy key to the container and setup the key inside the container.

• The main steps for the Dockerfile are:

  • Create a .ssh folder.

  • Copy the deploy key into the .ssh folder.

  • Add gitlab server to known_hosts file.

  • Setup .ssh/config file to explicitly specify the deploy key and username to be used.

  • Clone the repo.

• Here is some example Dockerfile code.

Docker build and run

At this stage, you should be able to use a browser to test that the Django server is up and running. Go to http://<server address>:8000.

Setup Docker Volume

A Docker volume is the preferred way of storing state information for the Docker container. For example, the db.sqlite3 file is best stored on a Docker volume, so that it can be referenced by any container. Therefore, as the Django project codebase develops, each version of the container can use the same data store.

• To create the Docker volume, on the host:

When running the container, the volume is mounted using the -v switch. The syntax for this switch is:

Establishing database file

After the first time python3 manage.py migrate has been run,

• Transfer the db.sqlite3 file to the mounted volume.

• Delete the db.sqlite3 file from its default location at the project root folder.

• Create a symlink at the project root folder called db.sqlite3 that points to the file on the mounted volume.

Database connection using entrypoint.sh

It is recommended that the entrypoint.sh script is used to establish the database connection. The general sequence in the entrypoint.sh script to connect the database on the volume is:

• Run makemigrations/ migrate. This creates a db.sqlite3 database file in its default location in the project root folder.

• Delete the db.sqlite3 file from the project root folder.

• Create a symlink to the database folder.

Here is an example of an entrypoint.sh script:

Start First App

• Navigate to the root directory of the Django project (where the manage.py file is located).

• Use manage.py to initialize the app:

Register app

Register the app with the project.

• Go to the project folder (e.g. /opt/ece_li_scheduling/ece_li_scheduling) where the settings.py file is stored.

• In the settings.py file, add the name of the new app to the INSTALLED_APPS list:

• In the urls.py file, direct all traffic for the new app to its .urls file.

  Note that include needs to be imported from django.urls.

Create urls.py

Since the project urls.py directs traffic to the app, the app needs to handle this traffic with its own urls.py file.

• Create a urls.py file within the app folder. Here is an example,

  Note that this example points to a home function in the app views, but this has not been created yet.

Create view

The app needs at least one view.

• Add a function to the app views.py file with a name that matches the function name specified in the urls.py file. Here is an example,