This is a guest contribution by Michael Bykovski. 

If you use the Divio Control Panel to create your project then, depending on your chosen configuration, the resulting Docker image will contain some ready-to-go content and configuration. 

This is a great way to get started quickly but what if you have an existing Docker image - perhaps you already have a project setup locally with your container image configured accordingly?

In this tutorial I wanted to explore how Divio can be used with a clean Docker image by simply dropping in any existing image.

Before we proceed, you will need a Divio account and have the Divio developer tools installed. 

This tutorial assumes a working knowledge of Git and familiarity with a Django project structure.

Create a new project

The first step is to create a new project from the Divio Control Panel - I have called mine “docker-tutorial”.

Choose following options when creating the project so we start with a minimal container image.


Configuration: "No Python"
 Type: "Blank"
 Boilerplate: "Blank Boilerplate"


Finally, choose your subscription configuration for the project depending on your needs. The free plan is a good choice for getting familiar with Divio and exploring the platform!

Setup your project

Navigate to a directory where your Divio project should be installed to. Let's say you want setup your project in /Development/docker-tutorial/

Navigate to /Development and invoke the Divio CLI (command line) tools:

divio project setup docker-tutorial

Note: the name must be consistent with what you decided to name your project in the first step. 

The resulting output will look something like:

Creating workspace

cloning project repository
Cloning into '/Users/divio/Development/docker-tutorial'...
Locking the website...
remote: Counting objects: 6, done.
remote: Compressing objects: 100% (4/4), done.
remote: Total 6 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (6/6), done.
Unlocking the website...
Error: Could not find a valid 'docker-compose.yml' file. Please make sure that this project has been updated on the Divio
Cloud to use Base Project version 3 or higher

Note the error message - this is to be expected since we did not choose any templates during project creation so there are no services configured and therefore no docker-compose file. The only files currently are an empty Dockerfile and

Move into the freshly created project. The full current path, depending on your naming, should look something like /Users/divio/Development/docker-tutorial

Create the docker-compose.yml file - in this tutorial we wont go into the structure of a docker-compose file since it is well covered in the official Docker documentation.

Example of the contents of my docker-compose.yml:

version: '3'

     image: postgres
       - ~/.docker/postgresql.11:/var/lib/postgresql/data
      build: .
        - "8888:80"
        - ".:/app"
      command: scripts/
        - DJANGO_SETTINGS_MODULE=docker_tutorial.settings.local
        - db
        - "db:postgres"

Note your application should be defined as "web" container and your database "db". This is how the Divio platform identifies your services.

The DJANGO_SETTINGS_MODULE=docker_tutorial.settings.local should be adjusted to reflect the name of your project if necessary.

We need to append a requirement to the Dockerfile . Paste the following to Dockerfile :

FROM python:3.7.0


COPY . /app
RUN pip3 install -r requirements.txt

CMD /app/scripts/

RUN pip3 install start

Note that the requirements.txt will be what you are using in your existing project.
You might wonder what the start package does - very simply it is a Divio package to start a single process from the Procfile .  You can examine the package in more detail at its Github repo.

Note: If you do not have pip3 or pip installed in your environment, install it using:

RUN apt-get update && apt-get install -y python-pip

Create a file called Procfile  in the root directory of your project with following content:

migrate: echo "Put Migration things here"

Finally, append following line to your .gitignore to prevent Divio files being added to your project repo. You will need to create this file if does not exist.


At this point you can test your application locally by running the project - add any files you wish and customise accordingly.

Now you need commit and push the project files. This is an important step since we will need to pull the files later. 

Git is a large topic which is out-of-scope for this tutorial - you can find a quick overview in the Getting started with Divio blog post.

Be sure to add your files before committing!

With our files safely stored, go one directory back with cd .. and execute the following command again. You should now be working the directory  /Development relative to this tutorial.

divio project setup docker-tutorial

Note that when we execute this command, the files we committed and pushed will down be pulled again into the fresh project.

You will be warned the directory already exists and we can safely continue:

The path /Users/docker-tutorial/workspace/docker-tutorial already exists and is not an empty directory.
Do you want to remove it and continue? [y/N]: y

The project files we will now be pulled and our new project will be created. 

Your workspace is setup and ready to start.

For Desktop Application:
 - click on the 'Start' button

For Terminal:
 - change directory to '/Users/docker-tutorial/workspace/docker-tutorial'
 - run 'divio project up'

We now have a freshly created Divio project complete you existing project integrated.

From here you can proceed to deploy to test or live environments and work with the Divio platform in the usual way!