cookiecutter-django/docs/developing-locally-docker.rst

135 lines
3.8 KiB
ReStructuredText
Raw Normal View History

Getting Up and Running with Docker
==================================
.. index:: Docker
The steps below will get you up and running with a local development environment.
All of these commands assume you are in the root of your generated project.
Prerequisites
--------------
2015-10-04 02:59:52 +03:00
If you don't already have these installed, get them all by installing `Docker Toolbox`_.
* docker
* docker-machine
* docker-compose
* virtualbox
2015-10-04 02:59:52 +03:00
.. _`Docker Toolbox`: https://github.com/docker/toolbox/releases
2015-10-04 02:54:01 +03:00
Create the Machine (Optional)
-------------------------------
2015-10-04 02:54:01 +03:00
On Ubuntu you have native Docker, so you don't need to create a VM with
docker-machine to use it.
However, on Mac/Windows/other systems without native Docker, you'll want to
start by creating a VM with docker-machine::
$ docker-machine create --driver virtualbox dev1
**Note:** If you want to have more than one docker development environment, then
name them accordingly. Instead of 'dev1' you might have 'dev2', 'myproject',
'djangopackages', et al.
Get the IP Address
--------------------
2015-10-04 02:56:53 +03:00
Once your machine is up and running, run this::
$ docker-machine ip dev1
123.456.789.012
2015-10-04 02:56:53 +03:00
This is also the IP address where the Django project will be served from.
Saving changes
--------------
If you are using OS X or Windows, you need to create a /data partition inside the
virtual machine that runs the docker deamon in order make all changes persistent.
If you don't do that your /data directory will get wiped out on every reboot.
2015-10-04 02:56:53 +03:00
To create a persistent folder, log into the virtual machine by running::
$ docker-machine ssh dev1
$ sudo su
2016-01-04 13:52:26 +03:00
$ mkdir /data
$ echo 'ln -sfn /mnt/sda1/data /data' >> /var/lib/boot2docker/bootlocal.sh
In case you are wondering why you can't use a host volume to keep the files on
your mac: As of `boot2docker` 1.7 you'll run into permission problems with mounted
host volumes if the container creates his own user and chown's the directories
on the volume. Postgres is doing that, so we need this quick fix to ensure that
all development data persists.
Build the Stack
---------------
This can take a while, especially the first time you run this particular command
2015-10-04 02:44:43 +03:00
on your development system::
$ docker-compose -f dev.yml build
If you want to build the production environment you don't have to pass an argument -f, it will automatically use docker-compose.yml.
Boot the System
---------------
This brings up both Django and PostgreSQL.
The first time it is run it might take a while to get started, but subsequent
runs will occur quickly.
Open a terminal at the project root and run the following for local development::
$ docker-compose -f dev.yml up
You can also set the environment variable ``COMPOSE_FILE`` pointing to ``dev.yml`` like this::
$ export COMPOSE_FILE=dev.yml
And then run::
$ docker-compose up
2015-10-04 02:44:43 +03:00
Running management commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As with any shell command that we wish to run in our container, this is done
using the ``docker-compose run`` command.
To migrate your app and to create a superuser, run::
2016-01-04 13:52:26 +03:00
$ docker-compose -f dev.yml run django python manage.py migrate
$ docker-compose -f dev.yml run django python manage.py createsuperuser
2015-10-04 02:44:43 +03:00
Here we specify the ``django`` container as the location to run our management commands.
Production Mode
~~~~~~~~~~~~~~~~
Instead of using `dev.yml`, you would use `docker-compose.yml`.
Other Useful Tips
------------------
Make a machine the active unit
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This tells our computer that all future commands are specifically for the dev1 machine.
Using the ``eval`` command we can switch machines as needed.
::
$ eval "$(docker-machine env dev1)"
Detached Mode
~~~~~~~~~~~~~
2015-10-04 22:09:18 +03:00
If you want to run the stack in detached mode (in the background), use the ``-d`` argument:
2015-10-04 22:09:18 +03:00
::
2016-01-04 13:52:26 +03:00
$ docker-compose -f dev.yml up -d