Using Discloud's discloud.yml to Define Processes, Env Vars, and Build Steps

Useful answer

Discloud lets you store the core runtime configuration of an application in a file named discloud.yml at the root of your repository. When you push this file and trigger a deployment, Discloud reads it to set up processes, environment variables, and build steps, so you no longer need to configure those items exclusively through the web dashboard.

Mechanism – worked example

The following discloud.yml defines a single web process, sets an environment variable, and specifies a build step that runs before the process starts.

# discloud.yml
processes:
  web:
    start: "node server.js"
env:
  NODE_ENV: "production"
build:
  command: "npm install && npm run build"

When Discloud processes this file:

1. It looks for the processes key and creates a process named web whose start command is node server.js.
2. It injects the environment variable NODE_ENV=production into the runtime environment.
3. During the build phase it executes npm install && npm run build before launching the process.

To apply this configuration:

1. Ensure you have the Discloud CLI installed and are logged in (discloud login).
2. Navigate to your local repository clone.
3. Add or edit discloud.yml at the repository root.
4. Commit and push the change to the branch you deploy from (e.g., git add discloud.yml && git commit -m "Add discloud.yml" && git push origin main).
5. Trigger a deployment via the CLI (discloud deploy) or through the dashboard.

Required permissions: you must have push access to the repository and permission to create or update deployments in the target Discloud project. The CLI will fail with an authentication error if you lack these rights.

Limits and verification

• The file must be valid YAML; only the top‑level keys processes, env, build, and addons are recognized. Any other keys are silently ignored.
• The total size of discloud.yml may not exceed 64 KB.
• Environment variables defined in the file are overridden by variables set in the Discloud dashboard; dashboard values take precedence.
• Discloud does not automatically use a Dockerfile present in the repo when a build section is defined. Docker builds are only used if you explicitly select a custom Docker build in the dashboard.

To verify that your file is being read:

1. After deployment, open the Discloud dashboard for your app and navigate to the “Logs” or “Processes” view. Confirm that the start command matches what you wrote in processes.web.start.
2. Check the environment variables (e.g., via a debug endpoint or the dashboard’s “Env Vars” tab) to see that NODE_ENV appears with the value you set.
3. To test the whitelist behavior, add an unsupported top‑level key such as foo: bar to the file, redeploy, and observe that the dashboard shows no error and the key has no effect.
4. To test precedence, define the same variable both in discloud.yml and in the dashboard with different values; the dashboard value will be the one that appears in the running environment.

Common mistakes

• Incorrect YAML indentation: mixing tabs and spaces or using inconsistent spacing causes Discloud to skip the file entirely and fall back to dashboard‑only configuration, with no warning message.
• Expecting a Dockerfile to be used: if you rely on a Dockerfile while also providing a build command, Discloud will ignore the Dockerfile and run the supplied command instead, which can lead to build failures if the command does not produce a runnable image.
• Assuming file changes take effect without pushing: editing discloud.yml locally but not committing and pushing the change leaves the live app using the previous configuration.

Practical way to check the result

After a deployment, run the following command to fetch the latest logs and verify the process start command:

# Replace <app-name> with your Discloud app identifier
discloud logs --app <app-name> --lines 20

Look for a line similar to:
Starting web process: node server.js

If you see the dashboard’s default start command or no process start line, the discloud.yml was likely ignored—double‑check YAML syntax and ensure the file is in the correct branch.