mirror of
https://github.com/cookiecutter/cookiecutter-django.git
synced 2024-11-22 17:47:08 +03:00
Added development and deployment instructions for Docker and EC2
This commit is contained in:
Garry Cairns
parent
ce5b7a1f59
commit
b925de21ce
|
|
@ -1,153 +1,66 @@
|
|||
# Makefile for Sphinx documentation
|
||||
#
|
||||
# Makefile for Sphinx LaTeX output
|
||||
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
PAPER =
|
||||
BUILDDIR = _build
|
||||
ALLDOCS = $(basename $(wildcard *.tex))
|
||||
ALLPDF = $(addsuffix .pdf,$(ALLDOCS))
|
||||
ALLDVI = $(addsuffix .dvi,$(ALLDOCS))
|
||||
|
||||
# Internal variables.
|
||||
PAPEROPT_a4 = -D latex_paper_size=a4
|
||||
PAPEROPT_letter = -D latex_paper_size=letter
|
||||
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
|
||||
# the i18n builder cannot share the environment and doctrees with the others
|
||||
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
|
||||
# Prefix for archive names
|
||||
ARCHIVEPRREFIX =
|
||||
# Additional LaTeX options
|
||||
LATEXOPTS =
|
||||
|
||||
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
|
||||
all: $(ALLPDF)
|
||||
all-pdf: $(ALLPDF)
|
||||
all-dvi: $(ALLDVI)
|
||||
all-ps: all-dvi
|
||||
for f in *.dvi; do dvips $$f; done
|
||||
|
||||
help:
|
||||
@echo "Please use \`make <target>' where <target> is one of"
|
||||
@echo " html to make standalone HTML files"
|
||||
@echo " dirhtml to make HTML files named index.html in directories"
|
||||
@echo " singlehtml to make a single large HTML file"
|
||||
@echo " pickle to make pickle files"
|
||||
@echo " json to make JSON files"
|
||||
@echo " htmlhelp to make HTML files and a HTML help project"
|
||||
@echo " qthelp to make HTML files and a qthelp project"
|
||||
@echo " devhelp to make HTML files and a Devhelp project"
|
||||
@echo " epub to make an epub"
|
||||
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
|
||||
@echo " latexpdf to make LaTeX files and run them through pdflatex"
|
||||
@echo " text to make text files"
|
||||
@echo " man to make manual pages"
|
||||
@echo " texinfo to make Texinfo files"
|
||||
@echo " info to make Texinfo files and run them through makeinfo"
|
||||
@echo " gettext to make PO message catalogs"
|
||||
@echo " changes to make an overview of all changed/added/deprecated items"
|
||||
@echo " linkcheck to check all external links for integrity"
|
||||
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
|
||||
all-pdf-ja:
|
||||
for f in *.pdf *.png *.gif *.jpg *.jpeg; do extractbb $$f; done
|
||||
for f in *.tex; do platex -kanji=utf8 $(LATEXOPTS) $$f; done
|
||||
for f in *.tex; do platex -kanji=utf8 $(LATEXOPTS) $$f; done
|
||||
for f in *.tex; do platex -kanji=utf8 $(LATEXOPTS) $$f; done
|
||||
-for f in *.idx; do mendex -U -f -d "`basename $$f .idx`.dic" -s python.ist $$f; done
|
||||
for f in *.tex; do platex -kanji=utf8 $(LATEXOPTS) $$f; done
|
||||
for f in *.tex; do platex -kanji=utf8 $(LATEXOPTS) $$f; done
|
||||
for f in *.dvi; do dvipdfmx $$f; done
|
||||
|
||||
zip: all-$(FMT)
|
||||
mkdir $(ARCHIVEPREFIX)docs-$(FMT)
|
||||
cp $(ALLPDF) $(ARCHIVEPREFIX)docs-$(FMT)
|
||||
zip -q -r -9 $(ARCHIVEPREFIX)docs-$(FMT).zip $(ARCHIVEPREFIX)docs-$(FMT)
|
||||
rm -r $(ARCHIVEPREFIX)docs-$(FMT)
|
||||
|
||||
tar: all-$(FMT)
|
||||
mkdir $(ARCHIVEPREFIX)docs-$(FMT)
|
||||
cp $(ALLPDF) $(ARCHIVEPREFIX)docs-$(FMT)
|
||||
tar cf $(ARCHIVEPREFIX)docs-$(FMT).tar $(ARCHIVEPREFIX)docs-$(FMT)
|
||||
rm -r $(ARCHIVEPREFIX)docs-$(FMT)
|
||||
|
||||
bz2: tar
|
||||
bzip2 -9 -k $(ARCHIVEPREFIX)docs-$(FMT).tar
|
||||
|
||||
# The number of LaTeX runs is quite conservative, but I don't expect it
|
||||
# to get run often, so the little extra time won't hurt.
|
||||
%.dvi: %.tex
|
||||
latex $(LATEXOPTS) '$<'
|
||||
latex $(LATEXOPTS) '$<'
|
||||
latex $(LATEXOPTS) '$<'
|
||||
-makeindex -s python.ist '$(basename $<).idx'
|
||||
latex $(LATEXOPTS) '$<'
|
||||
latex $(LATEXOPTS) '$<'
|
||||
|
||||
%.pdf: %.tex
|
||||
pdflatex $(LATEXOPTS) '$<'
|
||||
pdflatex $(LATEXOPTS) '$<'
|
||||
pdflatex $(LATEXOPTS) '$<'
|
||||
-makeindex -s python.ist '$(basename $<).idx'
|
||||
pdflatex $(LATEXOPTS) '$<'
|
||||
pdflatex $(LATEXOPTS) '$<'
|
||||
|
||||
clean:
|
||||
-rm -rf $(BUILDDIR)/*
|
||||
rm -f *.dvi *.log *.ind *.aux *.toc *.syn *.idx *.out *.ilg *.pla
|
||||
|
||||
html:
|
||||
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
||||
.PHONY: all all-pdf all-dvi all-ps clean
|
||||
.PHONY: all-pdf-ja
|
||||
|
||||
dirhtml:
|
||||
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
|
||||
|
||||
singlehtml:
|
||||
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
|
||||
@echo
|
||||
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
|
||||
|
||||
pickle:
|
||||
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
|
||||
@echo
|
||||
@echo "Build finished; now you can process the pickle files."
|
||||
|
||||
json:
|
||||
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
|
||||
@echo
|
||||
@echo "Build finished; now you can process the JSON files."
|
||||
|
||||
htmlhelp:
|
||||
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run HTML Help Workshop with the" \
|
||||
".hhp project file in $(BUILDDIR)/htmlhelp."
|
||||
|
||||
qthelp:
|
||||
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
|
||||
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
|
||||
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/{{ cookiecutter.repo_name }}.qhcp"
|
||||
@echo "To view the help file:"
|
||||
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/{{ cookiecutter.repo_name }}.qhc"
|
||||
|
||||
devhelp:
|
||||
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
|
||||
@echo
|
||||
@echo "Build finished."
|
||||
@echo "To view the help file:"
|
||||
@echo "# mkdir -p $$HOME/.local/share/devhelp/{{ cookiecutter.repo_name }}"
|
||||
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/{{ cookiecutter.repo_name }}"
|
||||
@echo "# devhelp"
|
||||
|
||||
epub:
|
||||
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
|
||||
@echo
|
||||
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
|
||||
|
||||
latex:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo
|
||||
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
|
||||
@echo "Run \`make' in that directory to run these through (pdf)latex" \
|
||||
"(use \`make latexpdf' here to do that automatically)."
|
||||
|
||||
latexpdf:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo "Running LaTeX files through pdflatex..."
|
||||
$(MAKE) -C $(BUILDDIR)/latex all-pdf
|
||||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
||||
|
||||
text:
|
||||
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
|
||||
@echo
|
||||
@echo "Build finished. The text files are in $(BUILDDIR)/text."
|
||||
|
||||
man:
|
||||
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
|
||||
@echo
|
||||
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
|
||||
|
||||
texinfo:
|
||||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
|
||||
@echo
|
||||
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
|
||||
@echo "Run \`make' in that directory to run these through makeinfo" \
|
||||
"(use \`make info' here to do that automatically)."
|
||||
|
||||
info:
|
||||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
|
||||
@echo "Running Texinfo files through makeinfo..."
|
||||
make -C $(BUILDDIR)/texinfo info
|
||||
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
|
||||
|
||||
gettext:
|
||||
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
|
||||
@echo
|
||||
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
|
||||
|
||||
changes:
|
||||
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
|
||||
@echo
|
||||
@echo "The overview file is in $(BUILDDIR)/changes."
|
||||
|
||||
linkcheck:
|
||||
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
|
||||
@echo
|
||||
@echo "Link check complete; look for any errors in the above output " \
|
||||
"or in $(BUILDDIR)/linkcheck/output.txt."
|
||||
|
||||
doctest:
|
||||
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
|
||||
@echo "Testing of doctests in the sources finished, look at the " \
|
||||
"results in $(BUILDDIR)/doctest/output.txt."
|
||||
|
|
|
|||
186
{{cookiecutter.repo_name}}/docs/docker_ec2.rst
Normal file
186
{{cookiecutter.repo_name}}/docs/docker_ec2.rst
Normal file
|
|
@ -0,0 +1,186 @@
|
|||
Developing with Docker
|
||||
======================
|
||||
|
||||
You can develop your application in a `Docker`_ container for simpler deployment onto bare Linux machines later. This instruction assumes an `Amazon Web Services`_ EC2 instance, but it should work on any machine with Docker > 1.3 and `Docker compose`_ installed.
|
||||
|
||||
.. _Docker: https://www.docker.com/
|
||||
.. _Amazon Web Services: http://aws.amazon.com/
|
||||
.. _Docker compose: https://docs.docker.com/compose/
|
||||
|
||||
Setting up
|
||||
^^^^^^^^^^
|
||||
|
||||
Docker encourages running one container for each process. This might mean one container for your web server, one for Django application and a third for your database. Once you're happy composing containers in this way you can easily add more, such as a `Redis`_ cache.
|
||||
|
||||
.. _Redis: http://redis.io/
|
||||
|
||||
The Docker compose tool (previously known as `fig`_) makes linking these containers easy. An example set up for your cookiecutter-django project might look like this:
|
||||
|
||||
.. _fig: http://www.fig.sh/
|
||||
|
||||
::
|
||||
|
||||
webapp/ # Your cookiecutter project would be in here
|
||||
Dockerfile
|
||||
...
|
||||
database/
|
||||
Dockerfile
|
||||
...
|
||||
webserver/
|
||||
Dockerfile
|
||||
...
|
||||
docker-compose.yml
|
||||
|
||||
Each component of your application would get its own `Dockerfile`_. The rest of this example assumes you are using the `base postgres image`_ for your database. Your database settings in `config/common.py` might then look something like:
|
||||
|
||||
.. _Dockerfile: https://docs.docker.com/reference/builder/
|
||||
.. _base postgres image: https://registry.hub.docker.com/_/postgres/
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
DATABASES = {
|
||||
'default': {
|
||||
'ENGINE': 'django.db.backends.postgresql_psycopg2',
|
||||
'NAME': 'postgres',
|
||||
'USER': 'postgres',
|
||||
'HOST': 'database',
|
||||
'PORT': 5432,
|
||||
}
|
||||
}
|
||||
|
||||
The `Docker compose documentation`_ explains in detail what you can accomplish in the `docker-compose.yml` file, but an example configuration might look like this:
|
||||
|
||||
.. _Docker compose documentation: https://docs.docker.com/compose/#compose-documentation
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
database:
|
||||
build: database
|
||||
webapp:
|
||||
build: webapp:
|
||||
command: /usr/bin/python3.4 manage.py runserver 0.0.0.0:8000 # dev setting
|
||||
# command: gunicorn -b 0.0.0.0:8000 wsgi:application # production setting
|
||||
volumes:
|
||||
- webapp/your_project_name:/path/to/container/workdir/
|
||||
links:
|
||||
- database
|
||||
webserver:
|
||||
build: webserver
|
||||
ports:
|
||||
- "80:80"
|
||||
- "443:443"
|
||||
links:
|
||||
- webapp
|
||||
|
||||
We'll ignore the webserver for now (you'll want to comment that part out while we do). A working Dockerfile to run your cookiecutter application might look like this:
|
||||
|
||||
::
|
||||
|
||||
FROM ubuntu:14.04
|
||||
ENV REFRESHED_AT 2015-01-13
|
||||
|
||||
# update packages and prepare to build software
|
||||
RUN ["apt-get", "update"]
|
||||
RUN ["apt-get", "-y", "install", "build-essential", "vim", "git", "curl"]
|
||||
RUN ["locale-gen", "en_GB.UTF-8"]
|
||||
|
||||
# install latest python
|
||||
RUN ["apt-get", "-y", "build-dep", "python3-dev", "python3-imaging"]
|
||||
RUN ["apt-get", "-y", "install", "python3-dev", "python3-imaging", "python3-pip"]
|
||||
|
||||
# prepare postgreSQL support
|
||||
RUN ["apt-get", "-y", "build-dep", "python3-psycopg2"]
|
||||
|
||||
# move into our working directory
|
||||
# ADD must be after chown see http://stackoverflow.com/a/26145444/1281947
|
||||
RUN ["groupadd", "python"]
|
||||
RUN ["useradd", "python", "-s", "/bin/bash", "-m", "-g", "python", "-G", "python"]
|
||||
ENV HOME /home/python
|
||||
WORKDIR /home/python
|
||||
RUN ["chown", "-R", "python:python", "/home/python"]
|
||||
ADD ./ /home/python
|
||||
|
||||
# manage requirements
|
||||
ENV REQUIREMENTS_REFRESHED_AT 2015-02-25
|
||||
RUN ["pip3", "install", "-r", "requirements.txt"]
|
||||
|
||||
# uncomment the line below to use container as a non-root user
|
||||
USER python:python
|
||||
|
||||
Running `sudo docker-compose build` will follow the instructions in your `docker-compose.yml` file and build the database container, then your webapp, before mounting your cookiecutter project files as a volume in the webapp container and linking to the database. Our example yaml file runs in development mode but changing it to production mode is as simple as commenting out the line using `runserver` and uncommenting the line using `gunicorn`.
|
||||
|
||||
Both are set to run on port `0.0.0.0:8000`, which is where the Docker daemon will discover it. You can now run `sudo docker-compose up` and browse to `localhost:8000` to see your application running.
|
||||
|
||||
Deployment
|
||||
^^^^^^^^^^
|
||||
|
||||
You'll need a webserver container for deployment. An example setup for `Nginx`_ might look like this:
|
||||
|
||||
.. _Nginx: http://wiki.nginx.org/Main
|
||||
|
||||
::
|
||||
|
||||
FROM ubuntu:14.04
|
||||
ENV REFRESHED_AT 2015-02-11
|
||||
|
||||
# get the nginx package and set it up
|
||||
RUN ["apt-get", "update"]
|
||||
RUN ["apt-get", "-y", "install", "nginx"]
|
||||
|
||||
# forward request and error logs to docker log collector
|
||||
RUN ln -sf /dev/stdout /var/log/nginx/access.log
|
||||
RUN ln -sf /dev/stderr /var/log/nginx/error.log
|
||||
VOLUME ["/var/cache/nginx"]
|
||||
EXPOSE 80 443
|
||||
|
||||
# load nginx conf
|
||||
ADD ./site.conf /etc/nginx/sites-available/your_cookiecutter_project
|
||||
RUN ["ln", "-s", "/etc/nginx/sites-available/your_cookiecutter_project", "/etc/nginx/sites-enabled/your_cookiecutter_project"]
|
||||
RUN ["rm", "-rf", "/etc/nginx/sites-available/default"]
|
||||
|
||||
#start the server
|
||||
CMD ["nginx", "-g", "daemon off;"]
|
||||
|
||||
That Dockerfile assumes you have an Nginx conf file named `site.conf` in the same directory as the webserver Dockerfile. A very basic example, which forwards traffic onto the development server or gunicorn for processing, would look like this:
|
||||
|
||||
::
|
||||
|
||||
# see http://serverfault.com/questions/577370/how-can-i-use-environment-variables-in-nginx-conf#comment730384_577370
|
||||
upstream localhost {
|
||||
server webapp_1:8000;
|
||||
}
|
||||
server {
|
||||
location / {
|
||||
proxy_pass http://localhost;
|
||||
}
|
||||
}
|
||||
|
||||
Running `sudo docker-compose build webserver` will build your server container. Running `sudo docker-compose up` will now expose your application directly on `localhost` (no need to specify the port number).
|
||||
|
||||
Building and running your app on EC2
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
All you now need to do to run your app in production is:
|
||||
|
||||
* Create an empty EC2 Linux instance (any Linux machine should do).
|
||||
|
||||
* Install your preferred source control solution, Docker and Docker compose on the news instance.
|
||||
|
||||
* Pull in your code from source control. The root directory should be the one with your `docker-compose.yml` file in it.
|
||||
|
||||
* Run `sudo docker-compose build` and `sudo docker-compose up`.
|
||||
|
||||
* Assign an `Elastic IP address`_ to your new machine.
|
||||
|
||||
.. _Elastic IP address: https://aws.amazon.com/articles/1346
|
||||
|
||||
* Point your domain name to the elastic IP.
|
||||
|
||||
**Be careful with Elastic IPs** because, on the AWS free tier, if you assign one and then stop the machine you will incur charges while the machine is down (presumably because you're preventing them allocating the IP to someone else).
|
||||
|
||||
Security advisory
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
The setup described in this instruction will get you up-and-running but it hasn't been audited for security. If you are running your own setup like this it is always advisable to, at a minimum, examine your application with a tool like `OWASP ZAP`_ to see what security holes you might be leaving open.
|
||||
|
||||
.. _OWASP ZAP: https://www.owasp.org/index.php/OWASP_Zed_Attack_Proxy_Project
|
||||
|
|
@ -13,6 +13,7 @@ Contents:
|
|||
|
||||
install
|
||||
deploy
|
||||
docker_ec2
|
||||
tests
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user