.. Do not change this document name! Referred to by: Aldryn django CMS repository Where: https://github.com/divio/aldryn-django-cms/readme.rst As: https://docs.divio.com/en/latest/background/addon-basics .. meta:: :description: Find documentation details on the basics of Aldryn (legacy). Although continued to be supported by our platform, we don't recommend using for new applications. .. _aldryn_addons: About Aldryn (legacy) ================================== .. note:: Aldryn continues to be supported by `Divio `_, but we do not recommend using Aldryn Django for new applications. The :ref:`Aldryn Django addons framework ` is an optional system that allows packages to be installed and configured very easily and in some cases fully automatically. What are Aldryn addons? ----------------------- Addons can be thought of as wrappers for Python packages such as Django or django CMS that allow them to take advantage of our addons framework. You'll see for example addons such as Aldryn Django (a wrapper/installer for Django) and Aldryn Django CMS (a wrapper/installer for django CMS). Aldryn Addons are provided as a convenience. If you'd like Django in your application, with all its settings configured for our infrastructure (uWSGI gateway, database, media storage etc), and in such a way that they will work correctly in the Live, Test and local environments, then Aldryn Django will take care of that for you; if it's installed, all that configuration and wiring will be done automatically. In the case of Aldryn Django CMS, it will configure settings such as ``MIDDLEWARE`` and ``TEMPLATES`` automatically. Packages as installed by Divio addons (such as Django or django CMS) are **completely standard and unmodified**. Installation and basic configuration of addons is managed via the application's dashboard in the Control Panel. More advanced configuration can be managed via :ref:`settings ` and :ref:`environment variables `. .. _dockerfile-reference-automatic-population: The Dockerfile in Aldryn Django applications ------------------------------------------------- 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 application creation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The ``Dockerfile`` starts life at application creation thus: .. code-block:: Dockerfile # # # # # # # # # # # # # # # # These sections are in effect placeholders for Docker commands and configuration that will be used to define the application later. The ```` section ~~~~~~~~~~~~~~~~~~~~~~~~~ The ```` is always populated. .. code-block:: Dockerfile :emphasize-lines: 2-4 # # Everything within sections like is generated and can # be automatically replaced on deployment. You can disable # this functionality by simply removing the wrapping tags. # .. _dockerfile-reference-DOCKER-FROM-section: The ```` section ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is determined by the application's base project version. If you update the base project in the application's *General Settings* in the Control Panel, this will be updated on the next deployment. For an application built on the ``aldryn/base-project:py3-3.23`` image, corresponding to the *Base Project:* ``Python 3 v3.23``: .. code-block:: Dockerfile :emphasize-lines: 2 # FROM aldryn/base-project:py3-3.23 # The ```` section ~~~~~~~~~~~~~~~~~~~~~~ This section will be supplied by a :ref:`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: .. code-block:: Dockerfile :emphasize-lines: 2-10 # 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 # The ```` section ~~~~~~~~~~~~~~~~~~~~~ If ``package.json`` (specifying Node packages that should be installed) is present in the root of the application, then instructions will be inserted to copy it to the root of the image and install the packages. .. code-block:: Dockerfile :emphasize-lines: 4-6 # # 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/*) # The ```` section ~~~~~~~~~~~~~~~~~~~~~~~ If both ``bower.json`` and ``.bowerrc`` are present in the root of the application, then the deployment process will insert: .. code-block:: Dockerfile :emphasize-lines: 2-6 # COPY bower.json .bowerrc /app/ RUN bower install \ --verbose \ --allow-root \ --config.interactive=false # .. _dockerfile-reference-python: The ```` section ~~~~~~~~~~~~~~~~~~~~~~~~ If ``requirements.in`` is present in the application, 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 application, for example: .. code-block:: Dockerfile :emphasize-lines: 2-10 # 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 # If ``requirements.txt`` is present in the application, then the ``pip-reqs compile`` instruction will be removed. See :ref:`How to pin all of your application's Python dependencies ` for why you might want to do this. .. _dockerfile-source-section: The ```` section ~~~~~~~~~~~~~~~~~~~~~~~~ The ``SOURCE`` section copies the application files to the ``/app`` directory of the container. .. code-block:: Dockerfile :emphasize-lines: 2 # COPY . /app # 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 ```` section ~~~~~~~~~~~~~~~~~~~~~~ If ``gulpfile.js`` is present in the root of the application, then instructions will be inserted to run the ``gulp build`` process: .. code-block:: Dockerfile :emphasize-lines: 2-3 # ENV GULP_MODE=production RUN gulp build # The ```` section ~~~~~~~~~~~~~~~~~~~~~~~~ ```` is always populated, with a command to copy static files to the location from where the web server will serve them: .. code-block:: Dockerfile :emphasize-lines: 2 # RUN DJANGO_MODE=build python manage.py collectstatic --noinput #