The Dockerfile
¶
Each Docker image is defined by a Dockerfile
, that
describes what is in the image and how containers
created from it should be built.
The Dockerfile is simply a text document, containing all the commands that would be issued on the
command-line to build an image - in short, the Dockerfile
defines an environment.
The Dockerfile is built automatically, and populated with appropriate commands (see below).
However, you can also add any commands you wish to the Dockerfile
, for example to install
system packages, or to configure the environment.
Important
The Dockerfile
executes its commands in sequence. This means that commands to install Node
(for example) must come before commands to run Node packages.
How the Dockerfile
is automatically populated¶
Hashes (#
) in the Dockerfile
indicate a comment. Sections within angle brackets are
autogenerated by the Divio Control Panel, and may be updated or changed on deployment without
warning.
Removing these wrapping tags will prevent a section being populated or changed.
The empty Dockerfile
at project creation¶
The Dockerfile
starts life at project creation thus:
# <WARNING>
# </WARNING>
# <DOCKER_FROM>
# </DOCKER_FROM>
# <NPM>
# </NPM>
# <BOWER>
# </BOWER>
# <PYTHON>
# </PYTHON>
# <SOURCE>
# </SOURCE>
# <GULP>
# </GULP>
# <STATIC>
# </STATIC>
These sections are in effect placeholders for Docker commands and configuration that will be used to define the project later.
The <WARNING>
section¶
The <WARNING>
is always populated.
# <WARNING>
# Everything within sections like <TAG> is generated and can
# be automatically replaced on deployment. You can disable
# this functionality by simply removing the wrapping tags.
# </WARNING>
The <DOCKER_FROM>
section¶
This is determined by the project’s base project version. If you update the base project in the project’s General Settings in the Control Panel, this will be updated on the next deployment.
For a project built on the aldryn/base-project:py3-3.23
image, corresponding to the Base
Project: Python 3 v3.23
:
# <DOCKER_FROM>
FROM aldryn/base-project:py3-3.23
# </DOCKER_FROM>
The <NODE>
section¶
This section will be supplied by a Boilerplate that includes Node components, for example in the django CMS Sass Boilerplate.
An example that uses other files supplied by the Boilerplate (such as install.sh
) to set up the
Node environment:
# <NODE>
ADD build /stack/boilerplate
ENV NODE_VERSION=6.10.1 \
NPM_VERSION=3.10.10
RUN bash /stack/boilerplate/install.sh
ENV NODE_PATH=$NVM_DIR/versions/node/v$NODE_VERSION/lib/node_modules \
PATH=$NVM_DIR/versions/node/v$NODE_VERSION/bin:$PATH
# </NODE>
The <NPM>
section¶
If package.json
(specifying Node packages that should be installed) is present in the root of
the project, then instructions will be inserted to copy it to the root of the image and install the
packages.
# <NPM>
# package.json is put into / so that mounting /app for local
# development does not require re-running npm install
ENV PATH=/node_modules/.bin:$PATH
COPY package.json /
RUN (cd / && npm install --production && rm -rf /tmp/*)
# </NPM>
The <BOWER>
section¶
If both bower.json
and .bowerrc
are present in the root of the project, then the
deployment process will insert:
# <BOWER>
COPY bower.json .bowerrc /app/
RUN bower install \
--verbose \
--allow-root \
--config.interactive=false
# </BOWER>
The <PYTHON>
section¶
If requirements.in
is present in the project, then at deployment time the Control Panel will
ensure that this section contains appropriate instructions to handle installation of Divio
Cloud addons and other packages. The exact contents of this section will depend on the project,
for example:
# <PYTHON>
ENV PIP_INDEX_URL=${PIP_INDEX_URL:-https://wheels.aldryn.net/v1/aldryn-extras+pypi/${WHEELS_PLATFORM:-aldryn-baseproject-py3}/+simple/} \
WHEELSPROXY_URL=${WHEELSPROXY_URL:-https://wheels.aldryn.net/v1/aldryn-extras+pypi/${WHEELS_PLATFORM:-aldryn-baseproject-py3}/}
COPY requirements.* /app/
COPY addons-dev /app/addons-dev/
RUN pip-reqs compile && \
pip-reqs resolve && \
pip install \
--no-index --no-deps \
--requirement requirements.urls
# </PYTHON>
If requirements.txt
is present in the project, then the pip-reqs compile
instruction will
be removed. See How to pin all of your project’s Python dependencies
for why you might want to do this.
The <SOURCE>
section¶
The SOURCE
section copies the project files to the /app
directory of the container.
# <SOURCE>
COPY . /app
# </SOURCE>
We do this late in our Dockerfile
by default. This is because it copies the entire repository
into the container, meaning that if anything is changed in the repository, it would invalidate
all the following layers, which would have to be rebuilt from scratch rather than using cached
layers. For reasons of economy, we keep this as late as possible.
If other parts of the repository need to be copied into the container earlier in the process, these should be explicitly specified as required.
The <GULP>
section¶
If gulpfile.js
is present in the root of the project, then instructions will be inserted to run
the gulp build
process:
# <GULP>
ENV GULP_MODE=production
RUN gulp build
# </GULP>
The <STATIC>
section¶
<STATIC>
is always populated, with a command to copy static files to the location from where
the web server will serve them:
# <STATIC>
RUN DJANGO_MODE=build python manage.py collectstatic --noinput
# </STATIC>