How to configure an existing Django project to use Aldryn¶
Initial project setup¶
Create a new project in the Divio Control Panel. You’ll need to make sure that the project options are appropriate, including the Python version and project type.
There are a number of available project types, including Django, Django-plus-django CMS and Django-plus-Wagtail, that are already set up with the relevant addon packages.
In general, if the software included in your project already exists on Divio as an Addon, it’s recommended to use the packaged addon version. This will help ensure not only that it is suitably configured for Divio, but that it will also co-exist well with other components.
Select the Boilerplate you want to use. Several are available, with different built-in frontend components to work with. If you choose a complex Boilerplate and later decide that you don’t need its functionality, it’s easy to remove from a project. However, select the Blank Boilerplate if you are sure you’d rather to set up and manage your site’s frontend starting from scratch.
See Boilerplates for more on the subject.
Do not start a deployment yet - we’ll cover that later.
Check addon versions¶
For each of the key components in your project for which a Divio addon exists, check that it is set to the correct version in your project, via the project’s Manage addons. This could include:
- django CMS (as well as key applications such as Django Filer, Aldryn News & Blog and so on)
Note that the version you seek may exist in the Beta or Alpha release channels of the addon.
Set up the project locally¶
Once any addons have been appropriately configured, you’ll need to set the project up locally. (See the local setup section in the tutorial if this is new to you.)
Using the Divio CLI set up a local copy of the project:
divio project setup <your-project-slug>
Migrate your existing code base¶
Addons will install their dependencies, so there is no need to add those explicitly as requirements. Compare the output of:
docker-compose run --rm web pip list
with your existing project’s requirements, or the output of
pip list in its environment, to see
what requirements will need to be added manually. The missing dependencies will need to be added
requirements.in file. See How to install Python dependencies in a project for more on adding Python
packages to the project.
Your project may also have some other requirements; see How to install system packages in a project.
Add application code¶
If your project contains custom applications that are part of the project itself (i.e. they live in directories inside the project, and are not reusable applications or libraries installed via Pip), copy them into the project directory.
If you decide in the future that these application should be packaged as reusable addons, that can be done later. See How to package a Django application as an Aldryn addon.
Add templates and static files¶
Your project’s templates similarly need to be copied to the new project’s
and static files to
The settings for your project and its applications need to be added to
Do not simply copy all your settings into the file. This will not work as expected.
Add them in the appropriate way, which will depend on how they are configured.
It can be a tedious and error-prone process to get all the
INSTALLED_APPS correct, without
either missing or duplicating any. It will help to get a complete list, sorted alphabetically, and to run a
diff on the list from each project.
Add the following to the end of the
settings.py of both your
source project and the new Divio project:
for app in sorted(INSTALLED_APPS): print(app)
For the original project, run:
python manage.py shell
and for the Divio project run:
docker-compose run --rm web python manage.py shell
In each case, copy the list of applications into a file and save the file. Now run a
the two files:
diff original-installed-apps new-installed-apps
In the output you will see lines starting with:
>- an application present in the Divio project, but not in the original
<- an application listed in the original, but not in the Divio project
In the first case, no action is required. In the second case, you may see entries such as:
and you will know that this application has not yet been added to your Divio project’s
(Once done, don’t forget to remove the lines you added.)
Divio projects use Postgres databases by default, with other options available. It’s beyond the scope of this document to cover all possible eventualities of database importing.
In the examples below
<container_name> will usually be something like
<project_slug>_db_1 - but you can confirm this by running
➜ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 71fe7e930f60 postgres:9.6 "docker-entrypoint..." About an hour ago Up About an hour 5432/tcp import_project_db_1 [...]
The NAMES column will list the container name.
Example of Postgres-to-Postgres migration¶
If you’re already using Postgres, you’re likely to find that steps along these lines will work:
Drop the database of the newly-created project:
docker exec <container_name> dropdb -U postgres db --if-exists
Create a new, empty database:
docker exec <container_name> createdb -U postgres db
docker exec <container_name> psql -U postgres --dbname=db -c "CREATE EXTENSION IF NOT EXISTS hstore"
Finally, assuming that you have already dumped your existing database to a local file, import it:
docker exec -i <container_name> psql -U postgres --dbname db < /path/to/dump
Migrating from one database to another¶
If you need to convert your existing database, you can use a conversion script such as https://github.com/lanyrd/mysql-postgresql-converter.
Alternatively, you can export the data to a JSON file (via Django’s
manage.py dumpdata command)
and then load it back into the new database with
You may find these resources useful:
Once you have loaded your data, check that its migrations are in order, using the
Media files should be copied to your project’s
Test the local site¶
You’re now in a position to test the local site, which should be done thoroughly. Start it up with:
divio project up
Upload your changes back to the Divio¶
Your project is a Git repository (certain files and directories are excluded), and should be
pushed to Git server in the usual way (
Media files are not included in the Git repository (static files are however) and must be pushed:
divio project push media
And the database also needs to be pushed:
divio project push db
The project can now be deployed on the Test server:
divio project deploy