qoqa is a command line application to help setup django projects and package them as debian(.deb) packages._
- Qoqa is a Zulu word which roughly translates to collect.
This project is mainly targeting small to medium sized django projects._
- devsctipts,
- dpkg
- dpkg-dev
- dh-virtualenv (>= 1.0)
- python3.5
- python3-venv
- python3-setuptools
- dh-python
We'll go through the usage of qoqa by creating a full django project, packaging and deploying it
To create a new Django project the following command is used
$qoqa --new fruit
The above command will launch an interactive session asking a few questions.
At this current stage only sqlite3 and postgresql databases are supported
After the interactive session, qoqa will begin to download some packages from pip mainly
- Django
- Whitenoise
- Gunicorn
- Django-debug-toolbar
A directory with the following file structure will be created.
- fruit
- env
- fruit
The env directory houses all the virtual environment files.
- env
- bin
- lib
- etc......
The fruit subdirectory will contain the traditional django project structure with some additional files and modifications
- fruit
- fruit
- fruit.cfg
- init.py
- manage.py
- production.cfg
The fruit.cfg file will contain some variables that will be used by django's settings.py file This is an example as to how the fruit.cfg file will look
[STATUS]
production = False
[SECRET_KEY]
value = "$2[Qt8a_|j+kqF-2kdbn8ii4qn)?n8\gSXr$jHA)E[ga2]`uX
[DEVELOPMENT_DATABASE]
name = development_db.sqlite3
database = sqlite3
[ALLOWED_HOSTS]
hosts = 127.0.0.1,localhost
The production.cfg file looks somewhat similar to the fruit.cfg file, just that production will be set to True and the secret key value will be different.
When the django project gets placed in a production environment, the production.cfg will will be renamed to fruit.cfg since that is what the fruit/settings.py file will be looking for.
The fruit/settings.py has been modified to accomodate the fruit.cfg file.
The Modifed fruit/settings.py is created via the django startproject template argument
So lets create a couple of django applications via the manage.py file (Dont forget to activate your virtual environment)
./manage.py startapp apple
./manage.py startapp banana
So now we have the following directory structure
- fruit
- apple
- banana
- fruit
- fruit.cfg
- manage.py
- production.cfg
- init.py
So now we can continue on developing our project the usual way.
So now you are ready to build and release your django project.
First we'll need create a requirements.txt file
$pip freeze > requirements.txt
This command needs to be run in the same directory as the projects env directory.
$qoqa --build 0.1.0
This command needs to be run in the same directory as the env directory
The above command will generate the required files needed to begin the release process.
If it's the first time running the command it will generate the following files and directories
- fruit
- debian
- MANIFEST.in
- requirements.txt
- setup.py
The debian directory contains the following files
- changelog - contains documentation about all the changes made to the package.
- compat - sets he compatibility level of the build.
- control - contains details about the project eg: Descriptions, dependencies etc.
- fruit.service - This is a systemd unit file that will run the django project as a service.
- postinst - This file contains details about what should happen after a package has been installed
- rules
If you want to read more about the debian directory and what type of files can be placed in here, you can read this guide
This is how the file will look
from setuptools import setup, find_packages
setup(
name='fruit',
version='0.1.0',
packages=find_packages(),
package_data={
},
# This is the data specified in the MANIFEST.in
include_package_data=True,
)
The find_packages() function searches for all python packages thats why the init.py is there under the fruit directory.
We are treating the entire django project as a python package, allowing for the apple and banana packages to fall under the fruit package.
The package_data keyword argument is used to install other data files related to the package, so we'll be placing *.djhtml, *.css, and *.js files from our django applications.
package_data = {
'fruit': [
'apple/static/apple/css/*.css',
'apple/static/apple/js/*.js'
'apple/templates/apple/*.djhtml',
'banana/templates/banana/*.djhtml',
'banana/static/banana/css/*.css',
'banana/static/banana/js/*.js'
etc........
]
}
More details about the setup.py file and configurations can be found here
We are now ready to create a .deb file
$qoqa --release 0.1.0
The debian/changelog file will open up allowing you to make any final changes. In the background, the above runs
dpkg-buildpackage -us -uc
The whole building process and .deb creation is created by dh-virtualenv
From the dh-virtualenv github page
dh-virtualenv is a tool that aims to combine Debian packaging with self-contained virtualenv based Python deployments.
Once the build process is complete a fruit_0.1.0.deb file will be created.
To install the package
$sudo dpkg -i fruit_0.1.0.deb
This will install the package in
/opt/venvs/fruit/
To start the application
$systemctl start fruit
The application should now be running on 0.0.0.0:8000
- The application is served via [Gunicorn|(http://gunicorn.org/) and not Django's development server
- Whitenoise handles the static files