cookiecutter/cookiecutter-django
1
1
Fork 0
mirror of https://github.com/cookiecutter/cookiecutter-django.git synced 2024-11-22 17:47:08 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update the docs

Browse Source
This commit is contained in:
Nikita P. Shupeyko 2018-03-09 21:17:56 +03:00
parent 05e97777e2
commit a31f5090d1
4 changed files with 105 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

88
docs/deployment-with-docker.rst
View File

@ -1,72 +1,66 @@
Deployment with Docker
======================
.. index:: Docker, deployment
.. index:: deployment, docker, docker-compose, compose
Prerequisites
-------------
* Docker (at least 1.10)
* Docker Compose (at least 1.6)
* Docker 1.10+.
* Docker Compose 1.6+
Understand the Compose Setup
----------------------------
Before you start, check out the `production.yml` file in the root of this project. This is where each component
of this application gets its configuration from. Notice how it provides configuration for these services:
Understanding the Docker Compose Setup
--------------------------------------
* `postgres` service that runs the database
* `redis` for caching
* `caddy` as webserver
* `django` is the Django project run by gunicorn
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:
If you chose the `use_celery` option, there are two more services:
* ``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.
* `celeryworker` which runs the celery worker process
* `celerybeat` which runs the celery beat process
Provided you have opted for Celery (via setting ``use_celery`` to ``y``) there are two more services:
Populate .env With Your Environment Variables
---------------------------------------------
* ``celeryworker`` running a Celery worker process;
* ``celerybeat`` running a Celery beat process.
Some of these services rely on environment variables set by you. There is an `env.example` file in the
root directory of this project as a starting point. Add your own variables to the file and rename it to `.env`. This
file won't be tracked by git by default so you'll have to make sure to use some other mechanism to copy your secret if
you are relying solely on git.
It is **highly recommended** that before you build your production application, you set your POSTGRES_USER value here. This will create a non-default user for the postgres image. If you do not set this user before building the application, the default user 'postgres' will be created, and this user will not be able to create or restore backups.
Configuring the Stack
---------------------
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. This should be enough to report crashes to Sentry.
The majority of services above are configured through the use of environment variables. Just check out :ref:`envs` and you will know the drill.
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
Optional: Use AWS IAM Role for EC2 instance
------------------------------------
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 the `.env`. 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 a minimum permission of `AmazonS3FullAccess`.
-------------------------------------------
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/
HTTPS is on by default
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:
* In the `.env.example`, we have made it simpler for you to change the default `Django Admin` into a custom name through an environmental variable. This should make it harder to guess the access to the admin panel.
* 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 :code:`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.
* 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*.
HTTPS is configured by default
------------------------------
The Caddy webserver 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.
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.
@ -76,15 +70,13 @@ You can read more about this here at `Automatic HTTPS`_ in the Caddy docs.
(Optional) Postgres Data Volume Modifications
---------------------------------------------
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.
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.
Run your app with Docker Compose
--------------------------------
To get started, pull your code from source control (don't forget the `.env` file) and change to your projects root
directory.
Building & Running Production Stack
-----------------------------------
You'll need to build the stack first. To do that, run::
You will need to build the stack first. To do that, run::
docker-compose -f production.yml build
@ -104,9 +96,7 @@ If you need a shell, run::
docker-compose -f production.yml run --rm django python manage.py shell
To get an output of all running containers.
To check your logs, run::
To check the logs out, run::
docker-compose -f production.yml logs
@ -115,21 +105,21 @@ If you want to scale your application, run::
docker-compose -f production.yml scale django=4
docker-compose -f production.yml scale celeryworker=2
.. warning:: Don't run the scale command on postgres, celerybeat, or caddy.
.. warning:: don't try to scale ``postgres``, ``celerybeat``, or ``caddy``.
If you have errors, you can always check your stack with `docker-compose`. Switch to your projects root directory and run::
To see how your containers are doing run::
docker-compose -f production.yml ps
Supervisor Example
Example: Supervisor
-------------------
Once you are ready with your initial setup, you want to make sure that your application is run by a process manager to
survive reboots and auto restarts in case of an error. You can use the process manager you are most familiar with. All
it needs to do is to run `docker-compose -f production.yml up` in your projects root directory.
it needs to do is to run ``docker-compose -f production.yml up`` in your projects root directory.
If you are using `supervisor`, you can use this file as a starting point::
If you are using ``supervisor``, you can use this file as a starting point::
[program:{{cookiecutter.project_slug}}]
command=docker-compose -f production.yml up
@ -139,11 +129,11 @@ If you are using `supervisor`, you can use this file as a starting point::
autorestart=true
priority=10
Place it in `/etc/supervisor/conf.d/{{cookiecutter.project_slug}}.conf` and run::
Move it to ``/etc/supervisor/conf.d/{{cookiecutter.project_slug}}.conf`` and run::
supervisorctl reread
supervisorctl start {{cookiecutter.project_slug}}
To get the status, run::
For status check, run::
supervisorctl status

2
docs/developing-locally-docker.rst
View File

@ -77,6 +77,8 @@ Here, ``django`` is the target service we are executing 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.
.. _envs:
Configuring the Environment
---------------------------

100
docs/developing-locally.rst
View File

@ -3,74 +3,98 @@ 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
* virtualenv
* PostgreSQL
Setting Up Development Environment
----------------------------------
First make sure to create and activate a virtualenv_.
Make sure to have the following on your host:
.. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/
* virtualenv_;
* pip;
* PostgreSQL.
Then install the requirements for your local development::
First things first.
#. `Create a virtualenv`_.
#. Activate the virtualenv you have just created.
#. Install development requirements: ::
$ pip install -r requirements/local.txt
Then, create a PostgreSQL database with the following command, where `[project_slug]` is what value you entered for your project's `project_slug`::
#. Create a new PostgreSQL database (note: if this is the first time a database is created on your machine you might need to alter a localhost-related entry in your ``pg_hba.conf`` so as to utilize ``trust`` policy): ::
$ createdb [project_slug]
$ createdb <what you've entered as the project_slug at setup stage>
You can now run the usual Django ``migrate`` and ``runserver`` commands::
#. Apply migrations: ::
$ python manage.py migrate
$ python manage.py runserver
At this point you can take a break from setup and start getting to know the files in the project.
#. See the application being served through Django development server: ::
But if you want to go further with setup, read on.
$ python manage.py runserver 0.0.0.0:8000
(Note: the following sections still need to be revised)
.. _virtualenv: http://docs.python-guide.org/en/latest/dev/virtualenvs/
.. _`Create a virtualenv`: https://virtualenv.pypa.io/en/stable/userguide/
Setting Up Env Vars for Production
-----------------------------------
`Cookiecutter Django` uses the excellent `django-environ`_ package, which includes a ``DATABASE_URL`` environment variable to simplify database configuration in your Django settings.
Setup Email Backend
-------------------
Rename env.example to .env to begin updating the file with your own environment variables. To add your database, define ``DATABASE_URL`` and add it to the .env file, as shown below:
MailHog
~~~~~~~
.. parsed-literal::
.. note:: In order for the project to support MailHog_ it must have been bootstrapped with ``use_mailhog`` set to ``y``.
DATABASE_URL="postgres://*<pg_user_name>*:*<pg_user_password>*\ @127.0.0.1:\ *<pg_port>*/*<pg_database_name>*"
MailHog is used to receive emails during development, it is written in Go and has no external dependencies.
.. _django-environ: http://django-environ.readthedocs.io
For instance, one of the packages we depend upon, ``django-allauth`` sends verification emails to new users signing up as well as to the existing ones who have not yet verified themselves.
Setup your email backend
-------------------------
#. `Download the latest MailHog release`_ for your OS.
django-allauth sends an email to verify users (and superusers) after signup and login (if they are still not verified). To send email you need to `configure your email backend`_
#. Rename the build to ``MailHog``.
.. _configure your email backend: https://docs.djangoproject.com/en/dev/topics/email/#smtp-backend
#. Copy the file to the project root.
In development you can (optionally) use MailHog_ for email testing. MailHog is built with Go so there are no dependencies. To use MailHog:
#. Make it executable: ::
1. `Download the latest release`_ for your operating system
2. Rename the executable to ``mailhog`` and copy it to the root of your project directory
3. Make sure it is executable (e.g. ``chmod +x mailhog``)
4. Execute mailhog from the root of your project in a new terminal window (e.g. ``./mailhog``)
5. All emails generated from your django app can be seen on http://127.0.0.1:8025/
$ chmod +x MailHog
.. _Mailhog: https://github.com/mailhog/MailHog/
.. _Download the latest release: https://github.com/mailhog/MailHog/releases
#. Spin up another terminal window and start it there: ::
Alternatively simply output emails to the console via: ``EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'``
./MailHog
In production basic email configuration is setup to send emails with Mailgun_
#. Check out `<http://127.0.0.1:8025/>`_ to see how it goes.
Now you have your own mail server running locally, ready to receive whatever you send it.
.. _MailHog: https://github.com/mailhog/MailHog/
.. _`properly configured`: https://docs.djangoproject.com/en/dev/topics/email/#smtp-backend
Console
~~~~~~~
.. note:: If you have generated your project with ``use_mailhog`` set to ``n`` this will be a default setup.
Alternatively, deliver emails over console via ``EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'``.
In production, we have Mailgun_ configured to have your back!
.. _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 a little bit of `prep work`_.
Sass Compilation & Live Reloading
---------------------------------
.. _prep work: https://cookiecutter-django.readthedocs.io/en/latest/live-reloading-and-sass-compilation.html
If you’d like to take advantage of live reloading and Sass / Compass CSS compilation you can do so with a little bit of preparation_.
.. _`Download the latest MailHog release`: https://github.com/mailhog/MailHog/releases
.. _preparation: https://cookiecutter-django.readthedocs.io/en/latest/live-reloading-and-sass-compilation.html
Summary
-------
Congratulations, you have made it! Keep on reading to unleash full potential of Cookiecutter Django.

4
docs/live-reloading-and-sass-compilation.rst
View File

@ -1,5 +1,5 @@
Live reloading and Sass CSS compilation
=======================================
Sass Compilation & Live Reloading
=================================
If you'd like to take advantage of live reloading and Sass / Compass CSS compilation you can do so with a little bit of prep work.