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.