From e587fc72c843bb98f002e7bbc6692b2287fb08a1 Mon Sep 17 00:00:00 2001 From: "Nikita P. Shupeyko" Date: Wed, 7 Mar 2018 15:01:19 +0300 Subject: [PATCH] Document envs ins and outs --- docs/developing-locally-docker.rst | 92 +++++++++++++++++++----------- 1 file changed, 59 insertions(+), 33 deletions(-) diff --git a/docs/developing-locally-docker.rst b/docs/developing-locally-docker.rst index b4b1ebfd6..4dd6a4436 100644 --- a/docs/developing-locally-docker.rst +++ b/docs/developing-locally-docker.rst @@ -10,21 +10,15 @@ All of these commands assume you are in the root of your generated project. Prerequisites ------------- -You'll need at least Docker 1.10. +* Docker; if you don't have it yet, follow the `installation instructions`_; +* Docker Compose; refer to the official documentation for the `installation guide`_. -If you don't already have it installed, follow the instructions for your OS: - - - On Mac OS X, you'll need `Docker for Mac`_ - - On Windows, you'll need `Docker for Windows`_ - - On Linux, you'll need `docker-engine`_ - -.. _`Docker for Mac`: https://docs.docker.com/engine/installation/mac/ -.. _`Docker for Windows`: https://docs.docker.com/engine/installation/windows/ -.. _`docker-engine`: https://docs.docker.com/engine/installation/ +.. _`installation instructions`: https://docs.docker.com/install/#supported-platforms +.. _`installation guide`: https://docs.docker.com/compose/install/ -Attention Windows users ------------------------ +Attention, Windows Users +------------------------ Currently PostgreSQL (``psycopg2`` python package) is not installed inside Docker containers for Windows users, while it is required by the generated Django project. To fix this, add ``psycopg2`` to the list of requirements inside ``requirements/base.txt``:: @@ -37,20 +31,17 @@ Doing this will prevent the project from being installed in an Windows-only envi Build the Stack --------------- -This can take a while, especially the first time you run this particular command -on your development system:: +This can take a while, especially the first time you run this particular command on your development system:: $ docker-compose -f local.yml build Generally, if you want to emulate production environment use ``production.yml`` instead. And this is true for any other actions you might need to perform: whenever a switch is required, just do it! + Run the Stack ------------- -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. +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:: @@ -72,15 +63,12 @@ To run in a detached (background) mode, just:: Execute Management Commands --------------------------- -As with any shell command that we wish to run in our container, this is done -using the ``docker-compose -f local.yml run --rm`` command. - -To migrate your app and to create a superuser, run:: +As with any shell command that we wish to run in our container, this is done using the ``docker-compose -f local.yml run --rm`` command: :: $ docker-compose -f local.yml run --rm django python manage.py migrate $ docker-compose -f local.yml run --rm django python manage.py createsuperuser -Here, ``django`` is the target service we want to execute the commands against. +Here, ``django`` is the target service we are executing the commands against. (Optionally) Designate your Docker Development Server IP @@ -89,14 +77,55 @@ Here, ``django`` is the target service we want to execute the commands against. When ``DEBUG`` is set to ``True``, the host is validated against ``['localhost', '127.0.0.1', '[::1]']``. This is adequate when running a ``virtualenv``. For Docker, in the ``config.settings.local``, add your host development server IP to ``INTERNAL_IPS`` or ``ALLOWED_HOSTS`` if the variable exists. +Configuring the Environment +--------------------------- + +This is the excerpt from your project's ``local.yml``: :: + + # ... + + postgres: + build: + context: . + dockerfile: ./compose/production/postgres/Dockerfile + volumes: + - postgres_data_local:/var/lib/postgresql/data + - postgres_backup_local:/backups + env_file: + - ./.envs/.local/.postgres + + # ... + +The most important thing for us here now is ``env_file`` section enlisting ``./.envs/.local/.postgres``. Generally, the stack's behavior is governed by a number of environment variables (`env(s)`, for short) residing in ``envs/``, for instance, this is what we generate for you: :: + + .envs + ├── .local + │   ├── .django + │   └── .postgres + └── .production + ├── .caddy + ├── .django + └── .postgres + +By convention, for any service ``sI`` in environment ``e`` (you know ``someenv`` is an environment when there is a ``someenv.yml`` file in the project root), given ``sI`` requires configuration, a ``.envs/.e/.sI`` `service configuration` file exists. + +Consider the aforementioned ``.envs/.local/.postgres``: :: + + # PostgreSQL + # ------------------------------------------------------------------------------ + POSTGRES_USER=XgOWtQtJecsAbaIyslwGvFvPawftNaqO + POSTGRES_PASSWORD=jSljDz4whHuwO3aJIgVBrqEml5Ycbghorep4uVJ4xjDYQu0LfuTZdctj7y0YcCLu + +The two envs we are presented with here are ``POSTGRES_USER``, and ``POSTGRES_PASSWORD`` (by the way, their values have also been generated for you). You might have figured out already where these definitions will end up; it's all the same with ``django`` and ``caddy`` service container envs. + + Tips & Tricks ------------- Activate a Docker Machine ~~~~~~~~~~~~~~~~~~~~~~~~~ -This tells our computer that all future commands are specifically for the dev1 machine. -Using the ``eval`` command we can switch machines as needed.:: +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)" @@ -106,15 +135,11 @@ Debugging ipdb """"" -If you are using the following within your code to debug: - -:: +If you are using the following within your code to debug: :: import ipdb; ipdb.set_trace() -Then you may need to run the following for it to work as desired: - -:: +Then you may need to run the following for it to work as desired: :: $ docker-compose -f local.yml run --rm --service-ports django @@ -130,7 +155,8 @@ Mailhog When developing locally you can go with MailHog_ for email testing provided ``use_mailhog`` was set to ``y`` on setup. To proceed, -1. make sure ``mailhog`` container is up and running; -1. open up ``http://127.0.0.1:8025``. +#. make sure ``mailhog`` container is up and running; + +#. open up ``http://127.0.0.1:8025``. .. _Mailhog: https://github.com/mailhog/MailHog/