doprax.yaml Configuration Guide

Introduction

The doprax.yaml file is a YAML-based configuration file used for configuration management of your user’s applications within your cloud platform instances. It enables you to specify volumes, environment variables, and services related to your user’s apps.

This guide will walk you through each aspect of the configuration file, explain the purpose of each element, and provide examples to illustrate the concepts. Remember that proper indentation and syntax are essential in YAML files.

Structure of doprax.yaml

The doprax.yaml file has a specific structure designed to help you manage configurations for your user’s applications.

Main Section

The “main” section encompasses configurations that are specific to the user’s main application container.

Example:

main:
  volumes:
    - name: matomovol
      mount: /var/www/html/
  envs:
    - MATOMO_DATABASE_HOST: mysql
    - MATOMO_DATABASE_USERNAME: dbuser01
    - MATOMO_DATABASE_PASSWORD: random_2
      type: password
    - MATOMO_DATABASE_DBNAME: matomodb

Main Section

The “main” section in the doprax.yaml file is dedicated to configuring the main container of your user’s application. This container often serves as the core component of the application, and its settings are defined here for specific customization.

Volumes

In the “volumes” subsection of the “main” section, you define the volumes that will be mounted into the main container. Volumes allow your user’s application to store data persistently, separate from the container’s runtime filesystem. This is crucial for preserving data between container restarts and maintaining application state.

Each volume is defined using the following structure:

main:
  volumes:
    - name: volume_name
      mount: /path/in/container/

• volume_name: A meaningful name for the volume. This should be a unique identifier for the volume.
• mount: The path within the main container where the volume will be mounted. This path determines where the data will be accessible from inside the container.

Envs

The “envs” subsection of the “main” section allows you to set environment variables specific to the main container. Environment variables are used to pass configuration values to your user’s application, enabling it to adapt to different runtime environments.

Each environment variable is defined using the following structure:

main:
  envs:
    - ENV_VARIABLE_NAME: value

• ENV_VARIABLE_NAME: The name of the environment variable. This should be in uppercase with underscores.
• value: The value assigned to the environment variable.

Additionally, you can enhance the security of sensitive environment variables by marking them as passwords. This is particularly important when handling sensitive information like passwords, keys, or tokens. To mark an environment variable as a password, you can use the following structure:

main:
  envs:
    - SENSITIVE_VARIABLE: secret_value
      type: password

In this case, the type: password tag indicates that the value is sensitive and should be treated as a password. This can help ensure that the actual value is not inadvertently exposed.

Example

Here’s an example that combines both the “volumes” and “envs” sections within the “main” section of the doprax.yaml file:

main:
  volumes:
    - name: data_vol
      mount: /app/data/

  envs:
    - APP_NAME: MyApplication
    - API_KEY: abcd1234
    - DATABASE_URL: db.example.com
    - SECRET_KEY: secret_value
      type: password

In this example, the “data_vol” volume is mounted at the /app/data/ path within the main container. Additionally, several environment variables are set, including “APP_NAME,” “API_KEY,” “DATABASE_URL,” and a sensitive variable “SECRET_KEY,” which is marked as a password.

These configurations help your users’ application access persistent data through volumes and adapt to runtime environments using environment variables. The “Main” section ensures that the core of the application is properly configured and tailored to the user’s needs.

Services Section

The “services” section defines configurations for various services associated with the user’s application.

Example:

services:
  - mysql:
      tag: 5.6
      volumes:
        - name: mysql_vol
          mount: /var/lib/mysql/
      envs:
        - MYSQL_ROOT_PASSWORD: random_1
          type: password
        - MYSQL_DATABASE: matomodb
        - MYSQL_USER: dbuser01
        - MYSQL_PASSWORD: random_2
          type: password

Placeholder Values

Within the doprax.yaml file, you may encounter placeholder values like random_1, random_2, etc. These placeholders represent dynamically generated random values that are consistent across the configuration for your user’s application. Placeholder values are automatically generated during setup time and can be referenced in other parts of the configuration to maintain consistency.

Examples

Here are some examples of how to configure your doprax.yaml file for different scenarios:

main:
  volumes:
    - name: data_vol
      mount: /data/

  envs:
    - APP_NAME: MyApp
    - DEBUG: true

Complete example: “Matomo Analytics”. Checkout the app in the app market: https://www.doprax.com/app-market/matomo/.

Notice that the MATOMO_DATABASE_PASSWORD in the main envs is random_2 and also MYSQL_PASSWORD in the services section. This ensures that the same random dynamically generated value is passed to both so that the application has the password of the MySQL database.

main:
  volumes:
    - name:  matomovol
      mount: /var/www/html/
  envs:
    - MATOMO_DATABASE_HOST: mysql
    - MATOMO_DATABASE_USERNAME: dbuser01
    - MATOMO_DATABASE_PASSWORD: random_2
      type: password
    - MATOMO_DATABASE_DBNAME: matomodb

services:
  - mysql:
      tag: 5.6
      volumes:
        - name: mysql_vol
          mount: /var/lib/mysql/
      envs:
        - MYSQL_ROOT_PASSWORD: random_1
          type: password
        - MYSQL_DATABASE: matomodb
        - MYSQL_USER: dbuser01
        - MYSQL_PASSWORD: random_2
          type: password

Best Practices

• Use meaningful names for volumes and services to enhance clarity.
• Organize your doprax.yaml file with appropriate indentation for improved readability.
• Refrain from sharing sensitive information in the configuration file. Utilize placeholder values for secrets.