.. This Software (Dioptra) is being made available as a public service by the .. National Institute of Standards and Technology (NIST), an Agency of the United .. States Department of Commerce. This software was developed in part by employees of .. NIST and in part by NIST contractors. Copyright in portions of this software that .. were developed by NIST contractors has been licensed or assigned to NIST. Pursuant .. to Title 17 United States Code Section 105, works of NIST employees are not .. subject to copyright protection in the United States. However, NIST may hold .. international copyright in software created by its employees and domestic .. copyright (or licensing rights) in portions of software that were assigned or .. licensed to NIST. To the extent that NIST holds copyright in this software, it is .. being made available under the Creative Commons Attribution 4.0 International .. license (CC BY 4.0). The disclaimers of the CC BY 4.0 license apply to all parts .. of the software developed or licensed by NIST. .. .. ACCESS THE FULL CC BY 4.0 LICENSE HERE: .. https://creativecommons.org/licenses/by/4.0/legalcode .. _how-to-using-docker-compose-overrides: Use Docker Compose Override Files ================================= This guide explains how to use Docker Compose override files to customize your Dioptra deployment. Override files allow you to extend or modify the base ``docker-compose.yml`` configuration without editing it directly. Prerequisites ------------- * :ref:`how-to-prepare-deployment` - A configured Dioptra deployment * Familiarity with Docker Compose YAML syntax Why Use Override Files? ----------------------- The ``docker-compose.yml`` file is generated by the cookiecutter template and managed by ``cruft``. When you run ``cruft update``, this file may be regenerated with upstream changes. **If you edit docker-compose.yml directly**, your changes will conflict with template updates, requiring manual conflict resolution. **Using docker-compose.override.yml instead** keeps your customizations separate from the template-managed file. Docker Compose automatically merges both files when you run ``docker compose up``, and your override file remains untouched during ``cruft update``. Configuration Steps ------------------- .. rst-class:: header-on-a-card header-steps Step 1: Create the Override File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The deployment template includes a ``docker-compose.override.yml.template`` file with commented examples for common customizations. Copy this template to create your override file: .. code:: sh cp docker-compose.override.yml.template docker-compose.override.yml .. important:: Only perform this copy **once** when first setting up customizations. If you have already created ``docker-compose.override.yml`` and added customizations, do not run this command again as it will overwrite your changes. .. rst-class:: header-on-a-card header-steps Step 2: Understand the File Structure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The override file uses standard Docker Compose syntax. To modify a service, specify the service name and only the properties you want to change or add. **Basic structure:** .. code:: yaml # Modify existing services services: service-name: # Properties here are merged with docker-compose.yml volumes: - "/host/path:/container/path:ro" environment: NEW_VAR: value # Define new named volumes volumes: volume-name: driver: local driver_opts: type: nfs o: "addr=,nfsvers=4" device: ":" .. note:: Replace ```` with your NFS server's IP address and ```` with the path to the exported directory on the NFS server. **How merging works:** - **Scalar values** (strings, numbers): Override file values replace base values - **Lists** (like ``volumes:`` or ``ports:``): Items are appended, not replaced - **Mappings** (like ``environment:``): Keys are merged; override values take precedence .. rst-class:: header-on-a-card header-steps Step 3: Add Your Customizations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Open ``docker-compose.override.yml`` in a text editor and add your customizations. .. note:: In the examples below, replace ```` with your deployment's slugified name (default: ``dioptra-deployment``) and ```` with the absolute path to your data directory. **Example: Adding a volume mount to a worker** .. code:: yaml services: -tfcpu-01: volumes: - ":/dioptra/data:ro" **Example: Setting environment variables** .. code:: yaml services: -tfgpu-01: environment: NVIDIA_VISIBLE_DEVICES: 0 **Example: Using a custom-built image for a specific worker** If you are using downloaded images but need to use a custom-built image for a specific worker (e.g., a modified GPU worker), you can override the image for that service. This is useful because downloaded and locally built images have different registry prefixes. See :ref:`how-to-get-container-images-registry-prefix` for more details. .. code:: yaml services: # Override image for a custom-built worker -tfgpu-01: image: dioptra/tensorflow2-gpu:dev .. note:: Replace ``dioptra/tensorflow2-gpu:dev`` with the name and tag of your custom-built image. **Example: Multiple customizations in one file** You can combine multiple customizations in a single override file: .. code:: yaml services: # Mount data directory to CPU worker -tfcpu-01: volumes: - ":/dioptra/data:ro" # Configure GPU assignment for GPU worker -tfgpu-01: environment: NVIDIA_VISIBLE_DEVICES: 0 volumes: - ":/dioptra/data:ro" # Define an NFS volume volumes: shared-data: driver: local driver_opts: type: nfs o: "addr=,auto,rw,bg,nfsvers=4,intr,actimeo=1800" device: ":" .. rst-class:: header-on-a-card header-steps Step 4: Apply Your Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~ After modifying the override file, restart the deployment to apply changes: .. code:: sh docker compose down docker compose up -d Verify the configuration was applied: .. code:: sh docker compose config This command shows the merged configuration that Docker Compose will use. .. rst-class:: header-on-a-card header-seealso See Also -------- **Common Customizations:** * :ref:`how-to-data-mounts` - Mount data volumes into worker containers * :ref:`how-to-gpu-enabled-workers` - Configure GPU assignments * :ref:`how-to-integrating-custom-containers` - Add custom containers * :ref:`how-to-enabling-ssl-tls` - Enable SSL/TLS encryption **Reference:** * :ref:`reference-deployment-folder` - Deployment folder structure * `Docker Compose: Merge and override `__ - Official merge documentation * `Docker Compose specification `__ - Full YAML reference