From 698c990cbdfcbd93a2dbe4e074231f05fef5edfe Mon Sep 17 00:00:00 2001 From: Daniel Roy Greenfeld Date: Fri, 18 Sep 2015 14:26:29 -0700 Subject: [PATCH] Refactored the Docker docs and added indexes. --- README.rst | 2 +- docs/deployment-on-heroku.rst | 2 + docs/deployment-with-docker.rst | 2 + docs/developing-locally-docker.rst | 108 ++++++++++++++++++++++++++++- docs/developing-locally.rst | 6 ++ docs/faq.rst | 2 + docs/index.rst | 4 +- docs/linters.rst | 2 +- 8 files changed, 124 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index f1b03db32..72b8713f6 100644 --- a/README.rst +++ b/README.rst @@ -126,7 +126,7 @@ Now take a look at your repo. Don't forget to carefully look at the generated RE For development, see the following for local development: * `Developing locally`_ -* Developing locally using docker +* `Developing locally using docker`_ .. _`Developing locally`: http://cookiecutter-django.readthedocs.org/en/latest/developing-locally.html .. _`Developing locally using docker`: http://cookiecutter-django.readthedocs.org/en/latest/developing-locally-docker.html diff --git a/docs/deployment-on-heroku.rst b/docs/deployment-on-heroku.rst index 782eb641b..6ee99fee2 100644 --- a/docs/deployment-on-heroku.rst +++ b/docs/deployment-on-heroku.rst @@ -1,6 +1,8 @@ Deployment on Heroku ==================== +.. index:: Heroku + You can either push the 'deploy' button in your generated README.rst or run these commands to deploy the project to Heroku: .. code-block:: bash diff --git a/docs/deployment-with-docker.rst b/docs/deployment-with-docker.rst index 6b5fece14..e5b0bfd45 100644 --- a/docs/deployment-with-docker.rst +++ b/docs/deployment-with-docker.rst @@ -1,6 +1,8 @@ Deployment with Docker ================================================= +.. index:: Docker, deployment + TODO: Review and revise **Warning** diff --git a/docs/developing-locally-docker.rst b/docs/developing-locally-docker.rst index e266f524d..41a09b479 100644 --- a/docs/developing-locally-docker.rst +++ b/docs/developing-locally-docker.rst @@ -1,6 +1,112 @@ Getting Up and Running with Docker ================================== +.. index:: Docker + +The steps below will get you up and running with a local development environment. + +Prerequisites +-------------- + +* docker +* docker-machine +* docker-compose +* virtualbox + +If you don't already have these installed, you can get them at: + +* https://github.com/docker/toolbox/releases +* https://www.virtualbox.org/wiki/Downloads + +Go to the Root of your Project +------------------------------ + +All of these commands assume you are in the root of your generated project. + +Create the 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. + +Make the new machine the active unit +------------------------------------- + +This tells our computer that all future commands are specifically for the just +created machine. Using the ``eval`` command we can switch machines as needed. + +:: + + $ eval "$(docker-machine env dev1)" + +Get the IP Address +-------------------- + +Acquiring the IP Address is good for two reasons: + +1. Confirms that the machine is up and running. +2. Tells us the IP address where our Django project is being served. + +:: + + $ docker-machine ip dev1 + 123.456.789.012 + +Build the Stack +--------------- + +This can take a while, especially the first time you run this particular command +on your development system. + +:: + $ docker-compose build + +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. + +:: + + $ docker-compose -f dev.yml up + +If you want to run the entire system in production mode, then run: + +:: + + $ docker-compose up + +If you want to run the stack in detached mode (in the background), use the ``-d`` argument:: + +:: + + $ docker-compose up -d + +Running bash commands (i.e. management commands) +---------------------------------------------------- + +This is done using the ``docker-compose run`` command. In the following examples +we specify the ``django`` container as the location to run our management commands. + +Example: + + $ docker-compose run django python manage.py migrate + $ docker-compose run django python manage.py createsuperuser + + + +Deprecated +========== + +**Note:** This segment of documentation is being kept in this location as part of our documentation transition process. + + The steps below will get you up and running with a local development environment. We assume you have the following installed: * docker @@ -39,5 +145,5 @@ And then:: $ 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 +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. diff --git a/docs/developing-locally.rst b/docs/developing-locally.rst index 6b7d2effd..d4fd87745 100644 --- a/docs/developing-locally.rst +++ b/docs/developing-locally.rst @@ -1,6 +1,8 @@ Getting Up and Running Locally ============================== +.. index:: pip, virtualenv, PostgreSQL + The steps below will get you up and running with a local development environment. We assume you have the following installed: * pip @@ -33,8 +35,12 @@ django-allauth sends an email to verify users (and superusers) after signup and In development you can (optionally) use Maildump_ for email testing. Or alternatively simply output emails to the console via: ``EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'`` +.. _Maildump: https://github.com/ThiefMaster/maildump + In production basic email configuration is setup to send emails with Mailgun_ +.. _Mailgun: https://www.mailgun.com/ + **Live reloading and Sass CSS compilation** If you'd like to take advantage of live reloading and Sass / Compass CSS compilation you can do so with the included Grunt task. diff --git a/docs/faq.rst b/docs/faq.rst index 9079aaee7..9ef546575 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -1,6 +1,8 @@ FAQ ==== +.. index:: FAQ, 12-Factor App + Why aren't you using just one configuration file (12-Factor App) ---------------------------------------------------------------------- diff --git a/docs/index.rst b/docs/index.rst index 0b876a187..820844fc3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -26,5 +26,7 @@ Indices and tables ================== * :ref:`genindex` -* :ref:`modindex` * :ref:`search` + +.. At some point it would be good to have a module index of the high level things +we are doing. Then we can * :ref:`modindex` back in. diff --git a/docs/linters.rst b/docs/linters.rst index 05b8e303e..3349faed9 100644 --- a/docs/linters.rst +++ b/docs/linters.rst @@ -1,4 +1,4 @@ Linters ======= -TODO +.. index:: linters