diploi.yaml Explained

The diploi.yaml file at the root of a Diploi repository is the Infrastructure as Code (IaC) configuration file Diploi uses to build the infrastructure for a deployment.
Our component-based model allows for easy configuration of stacks without making the config overly verbose. The more detailed config for a component, such as HELM charts and other setup files, are housed in dedicated GitHub repositories maintained by the component owners.

Tip

Read our blog post about our IaC implementation for more information.

diploiVersion: v1.0
components:
  - name: Next.js
    identifier: next
    package: https://github.com/diploi/component-nextjs#main
    env:
      include:
        - *
  - name: Bun
    identifier: bun
    folder: /api #Optional
    package: https://github.com/diploi/component-bun#main
    env:
      include:
        - postgres.*
  - name: Node.js
    identifier: node
    package: https://github.com/diploi/component-nodejs#main
    env:
      include:
        - postgres.POSTGRES_USER:DB_USER
addons:
  - name: PostgreSQL
    identifier: postgres
    package: https://github.com/diploi/addon-postgres#main

components and addons

The list of components and addons to be included in a project. Everything in this list can be edited and your infrastucture will adapt.

name

The display name for a component.

identifier

An internal identifier for a component. This has to be unique.

The identifier is used as the internal hostname for a component, and as the folder name where the component files are located.

Caution

If the folder parameter is not defined, Diploi will use the component identifier as the folder name where the files for your component will be stored.

folder

Indicates to Diploi where to store the files necessary for a component, and is meant to be used when you import an existing application that already has a functioning app running in a specific folder inside your repository.

If a component has a folder parameter assigned that already exists, Diploi will not generate any new files, and instead it will try to run the component using the files in the directory you are pointing to.

Note

If you plan to run staging and production stages for your project in Diploi or you need to customize how a component is run at startup, you will need to add a Dockerfile (used by staging and production deployments) and a Dockerfile.dev (used by development deployments) files to the folder you are pointing to.

You can get all of our officially supported Dockerfiles for all components in our GitHub repositories.

package

The URL for the package repository. Version comes after the hashtag # symbol. Version can be a Git tag or branch reference.

env

ENV values from other components aren’t available by default, but can be configured here. Importing an ENV variable means making it available for processes inside of a component.

Import From Other Components

Imports let you reuse ENV values from other components, keeping everything in sync and avoiding repetitive manual configuration.

Open the Options tab for any component to see the values it defines, review the ones it currently imports, and override individual entries whenever you need a custom value.

env:
  include:
    # Imports every ENV value from every component
    - *
    # Imports all ENV values from a component with the `postgres` identifier
    - postgres.*
    # Imports all ENV values that start with `POSTGRES_` from a component with the `postgres` identifier
    - postgres.POSTGRES_*
    # Imports all ENV values from all components where an identifier starts with `post`
    - post*
    # Imports the `POSTGRES_USER` ENV value from a component with the `postgres` identifier
    - postgres.POSTGRES_USER
    # Imports the `POSTGRES_USER` ENV value from a component with the `postgres` identifier and renames it to `DB_USER`
    - postgres.POSTGRES_USER:DB_USER

    # Alternative syntax for renaming
    - path: postgres.POSTGRES_USER
      name: DB_USER

You can use wildcards when importing values.

• *
  • Imports every ENV value from every component
• postgres.*
  • Imports all ENV values from a component with the postgres identifier
• postgres.POSTGRES_*
  • Imports all ENV values that start with POSTGRES_ from a component with the postgres identifier
• post*
  • Imports all ENV values from all components where an identifier starts with post
• postgres.POSTGRES_USER
  • Imports the POSTGRES_USER ENV value from a component with the postgres identifier

You can remap individual ENV values while importing them

• postgres.POSTGRES_USER:DB_USER
  • Imports the POSTGRES_USER ENV value from a component with the postgres identifier and renames it to DB_USER

Static Values

Static values let you define build-time variables that are exposed to GitHub Actions workflows.

env:
  include:
    - value: test
      name: TEST

Diploi forwards static values as Docker build arguments. You can access them inside your component’s Dockerfile and Dockerfile.dev with the ARG instruction and promote them to regular environment variables if needed.

ARG TEST
ENV TEST_VALUE=$TEST

Static values are scoped to the component where they are declared and remain consistent across deployments. Use the Options tab when you need runtime configuration instead. You can also overwrite a static ENV value in the Options tab without changing it in the config.