cookiecutter-django/docs/deployment-with-docker.rst

140 lines
5.8 KiB
ReStructuredText
Raw Normal View History

2015-09-18 20:20:48 +03:00
Deployment with Docker
======================
2015-09-18 20:20:48 +03:00
2018-03-09 21:17:56 +03:00
.. index:: deployment, docker, docker-compose, compose
Prerequisites
-------------
2015-09-18 20:20:48 +03:00
2018-03-09 21:17:56 +03:00
* Docker 1.10+.
* Docker Compose 1.6+
2015-09-18 20:20:48 +03:00
2018-03-09 21:17:56 +03:00
Understanding the Docker Compose Setup
--------------------------------------
2018-03-09 21:17:56 +03:00
Before you begin, check out the ``production.yml`` file in the root of this project. Keep note of how it provides configuration for the following services:
2018-03-09 21:17:56 +03:00
* ``django``: your application running behind ``Gunicorn``;
* ``postgres``: PostgreSQL database with the application's relational data;
* ``redis``: Redis instance for caching;
* ``caddy``: Caddy web server with HTTPS on by default.
2018-03-09 21:17:56 +03:00
Provided you have opted for Celery (via setting ``use_celery`` to ``y``) there are two more services:
* ``celeryworker`` running a Celery worker process;
* ``celerybeat`` running a Celery beat process.
2018-03-09 21:17:56 +03:00
Configuring the Stack
---------------------
2015-09-18 20:20:48 +03:00
2018-03-09 21:17:56 +03:00
The majority of services above are configured through the use of environment variables. Just check out :ref:`envs` and you will know the drill.
2018-03-09 21:17:56 +03:00
To obtain logs and information about crashes in a production setup, make sure that you have access to an external Sentry instance (e.g. by creating an account with `sentry.io`_), and set the ``DJANGO_SENTRY_DSN`` variable.
You will probably also need to setup the Mail backend, for example by adding a `Mailgun`_ API key and a `Mailgun`_ sender domain, otherwise, the account creation view will crash and result in a 500 error when the backend attempts to send an email to the account owner.
.. _sentry.io: https://sentry.io/welcome
.. _Mailgun: https://mailgun.com
2018-03-09 21:17:56 +03:00
Optional: Use AWS IAM Role for EC2 instance
2018-03-09 21:17:56 +03:00
-------------------------------------------
If you are deploying to AWS, you can use the IAM role to substitute AWS credentials, after which it's safe to remove the ``AWS_ACCESS_KEY_ID`` AND ``AWS_SECRET_ACCESS_KEY`` from ``.envs/.production/.django``. To do it, create an `IAM role`_ and `attach`_ it to the existing EC2 instance or create a new EC2 instance with that role. The role should assume, at minimum, the ``AmazonS3FullAccess`` permission.
.. _IAM role: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html
.. _attach: https://aws.amazon.com/blogs/security/easily-replace-or-attach-an-iam-role-to-an-existing-ec2-instance-by-using-the-ec2-console/
2018-03-09 21:17:56 +03:00
HTTPS is On by Default
----------------------
SSL (Secure Sockets Layer) is a standard security technology for establishing an encrypted link between a server and a client, typically in this case, a web server (website) and a browser. Not having HTTPS means that malicious network users can sniff authentication credentials between your website and end users' browser.
It is always better to deploy a site behind HTTPS and will become crucial as the web services extend to the IoT (Internet of Things). For this reason, we have set up a number of security defaults to help make your website secure:
2018-03-09 21:17:56 +03:00
* If you are not using a subdomain of the domain name set in the project, then remember to put the your staging/production IP address in the ``DJANGO_ALLOWED_HOSTS`` environment variable (see :ref:`settings`) before you deploy your website. Failure to do this will mean you will not have access to your website through the HTTP protocol.
* Access to the Django admin is set up by default to require HTTPS in production or once *live*.
2018-03-09 21:17:56 +03:00
The Caddy web server used in the default configuration will get you a valid certificate from Lets Encrypt and update it automatically. All you need to do to enable this is to make sure that your DNS records are pointing to the server Caddy runs on.
You can read more about this here at `Automatic HTTPS`_ in the Caddy docs.
.. _Automatic HTTPS: https://caddyserver.com/docs/automatic-https
2015-09-18 20:20:48 +03:00
(Optional) Postgres Data Volume Modifications
---------------------------------------------
2018-03-09 21:17:56 +03:00
Postgres is saving its database files to the ``postgres_data`` volume by default. Change that if you want something else and make sure to make backups since this is not done automatically.
2015-09-18 20:20:48 +03:00
2018-03-09 21:17:56 +03:00
Building & Running Production Stack
-----------------------------------
2015-09-18 20:20:48 +03:00
2018-03-09 21:17:56 +03:00
You will need to build the stack first. To do that, run::
2015-09-18 20:20:48 +03:00
docker-compose -f production.yml build
2015-09-18 20:20:48 +03:00
Once this is ready, you can run it with::
docker-compose -f production.yml up
2015-09-18 20:20:48 +03:00
To run a migration, open up a second terminal and run::
docker-compose -f production.yml run --rm django python manage.py migrate
2015-09-18 20:20:48 +03:00
To create a superuser, run::
docker-compose -f production.yml run --rm django python manage.py createsuperuser
2015-09-18 20:20:48 +03:00
If you need a shell, run::
docker-compose -f production.yml run --rm django python manage.py shell
2015-09-18 20:20:48 +03:00
2018-03-09 21:17:56 +03:00
To check the logs out, run::
2015-09-18 20:20:48 +03:00
docker-compose -f production.yml logs
2015-09-18 20:20:48 +03:00
If you want to scale your application, run::
docker-compose -f production.yml scale django=4
docker-compose -f production.yml scale celeryworker=2
2015-09-18 20:20:48 +03:00
2018-03-09 21:17:56 +03:00
.. warning:: don't try to scale ``postgres``, ``celerybeat``, or ``caddy``.
2015-09-18 20:20:48 +03:00
2018-03-09 21:17:56 +03:00
To see how your containers are doing run::
docker-compose -f production.yml ps
2018-03-09 21:17:56 +03:00
Example: Supervisor
2016-06-08 22:33:18 +03:00
-------------------
Once you are ready with your initial setup, you want to make sure that your application is run by a process manager to
2016-06-08 22:33:18 +03:00
survive reboots and auto restarts in case of an error. You can use the process manager you are most familiar with. All
2018-03-09 21:17:56 +03:00
it needs to do is to run ``docker-compose -f production.yml up`` in your projects root directory.
2016-06-08 22:33:18 +03:00
2018-03-09 21:17:56 +03:00
If you are using ``supervisor``, you can use this file as a starting point::
2016-06-08 22:33:18 +03:00
[program:{{cookiecutter.project_slug}}]
command=docker-compose -f production.yml up
2016-06-08 22:33:18 +03:00
directory=/path/to/{{cookiecutter.project_slug}}
redirect_stderr=true
autostart=true
autorestart=true
priority=10
2018-03-09 21:17:56 +03:00
Move it to ``/etc/supervisor/conf.d/{{cookiecutter.project_slug}}.conf`` and run::
2016-06-08 22:33:18 +03:00
supervisorctl reread
supervisorctl start {{cookiecutter.project_slug}}
2018-03-09 21:17:56 +03:00
For status check, run::
2016-06-08 22:33:18 +03:00
supervisorctl status