Skip to main content
Sign in MENU

Understanding the docker-compose.yml file and parameters guide

  • Updated

A complete docker-compose.yml 

This article outlines all the configurable parameters that can be made within the docker compose YAML file. See below an example of a docker compose file which has every possible configurable parameter. 

version: '3.5'
services:
  apish:
    environment:
      DRAFTABLE_APISH_NGINX: |-
        nginx:
          virtual_hosts:
            draftable:
              conf_settings:
                http_redirects_to_https: False
                use_x_forwarded_proto: True
                access_control_allow_origin: desired-domain.tld
                real_ip_header_name: draftable_header
                real_ip_header_from: 190.168.10.80:80
                ssl:
                  certificate: /srv/draftable/config/certs/apish.crt
                  private_key: /srv/draftable/config/private/apish.key
    image: draftable/apish
    ports:
      - 80:80/tcp # HTTP
      - 440:443/tcp # HTTPS
    volumes:
      - draftable-apish:/srv/draftable
      - /sys/fs/cgroup:/sys/fs/cgroup 
volumes:
  draftable-apish:

You can copy and paste sections from the example above to form your own docker-compose.yml file. Just be sure to change the values to suit your installation. 

 

All docker-compose YAML parameters 

Below is an explanation each important field that can be configured to enable/disable certain features within the instance. You can also view the documentation on docker-composer created by docker. 

 

Default docker-compose parameters 

These are parameters that are required for APISH but are 

image:

This selects the image that is used to start the instance, only 1 image can be selected. Please ensure the image is already pulled before declaring it in the docker compose file. 

 

ports:

Notate which ports are opened for users to access the instance. Take note of the formatting of the ports settings. 

 

volumes (under apish):

This is where you donate the storage locations within the selection volume for both the volume data and cgroups. Ensure that the volume name used matches the other volumes field below. 

 

volumes:

Notate which volume is being used with the instance. When running docker-compose up if the volume named here does not match one that already exists, it will generate a new volume. Like the other volumes field, the volume declared needs to match. 

 

Draftable Self-hosted specific configuration settings 

All fields under conf_settings are additional features that have been added to the API Self-hosted product and can be customised here. See below for all the different fields that can be added and hence configured. 

 

http_redirects_to_http: 
Default value: True (Boolean)

If enabled, redirect HTTP requests to the equivalent HTTPS URL. Disabling should only be necessary if you want to allow "truly" insecure requests. When TLS connections are not being terminated on the server, you should instead enable  use_x_forwarded_proto, and ensure the use_x_forwarded_proto header is being set by upstream load balancers and reverse proxies.

For more information you can view our SSL termination instructions article.

 

use_x_forwarded_proto: 
Default: False (Boolean)

If enabled, check the use_x_forwarded_proto header in requests to determine the URI scheme (HTTP or HTTPS). The header will be passed through to the frontend server, and used to check if a HTTP redirect to the equivalent HTTPS URL should be sent when HTTPS request redirection is enabled.

For more information you can view our SSL termination instructions article.

 

access_control_allow_origin: 

Referring to the example YAML above, replacing desired-domain.tld with the domain you wish to permit cross-origin requests from. Once set, you'll see the relevant Access-Control-* headers be returned in requests to the container.

For more information you can view our CORs implementation setup article.

 

real_ip_header_name:
Default value: <null> (String)

Specifies the name of the HTTP header supplied in requests which contains the "real" IP address of the client. This can be used by load balancers and reverse proxies to communicate the IP address of the client, allowing the server to be aware of the IP address of clients making requests. The header used for this purpose is typically named use_x_forwarded_proto

 

real_ip_header_from:
Default value: [0.0.0.0:0] (IP address with ports expected)

Ifreal_ip_header_name has been set, specifies an array of IPv4 and IPv6 addresses trusted to provide real IP address information. If untrusted clients can access the server and set this header, they can effectively "spoof" their IP address. It's strongly recommended this setting be set to addresses of load balancers and reverse proxies forwarding requests.

 

ssl:

The two sub-fields under this field represent the certificate and private key locations which are used as part of custom certificate installation. 

  • certificate:

    • This notates which certificate is being used within the volume for ssl configuration. Note the value apish.crt in the YMAL example is just a placeholder name. 

  • private_key:

    • This notates which private key is being used within the volume for ssl configuration. Note the value apish.key in the YAML example is just a placeholder name. 

For the process of installing custom certificates, see installing customer certificates onto your Self-hosted

 

 

Related articles