Environments

Run the same mock as several independently-live servers (a prd, a stg, ...) from a single akuma.yml. Each environment can override parts of the config.

The default environment

Your config is the default environment as-is. With no environments: block, that is the only environment, and it is what akuma start and akuma deploy use.

Adding environments

Add a top-level environments: map. Each key is an environment name; its value is a partial config that overrides the base. The base is king: an environment only states what differs, everything else is inherited.

name: blog-api

schemas:
  Post:
    properties:
      id: number
      title: string

endpoints:
  - path: /posts
    method: GET
    response:
      type: array
      schema: Post

errors:
  notFound: { inline: { code: not_found } }

# Only what differs per environment, merged onto the base above.
environments:
  prd:
    errors:
      notFound: { inline: { code: gone, message: "in production" } }

How overrides merge

"Default is king, until overridden by environment." The merge is predictable:

• Maps (schemas, errors, defaultErrors, naming) deep-merge: an environment adds or replaces individual keys; keys it never mentions are inherited from the base.
• Scalars (name, description) are replaced by the environment's value.
• Lists (endpoints) are replaced wholesale if the environment supplies them; otherwise the base list is inherited.

Deploying an environment

Each environment is independently live with its own address. Deploy one with --env; with no flag, the default environment deploys. Named environments are a deploy-time choice: akuma start always runs the default environment locally.

akuma deploy            # the default environment
akuma deploy --env prd  # the prd environment

In the dashboard, the environment selector beside the server name switches which environment you are viewing; Deploy / Pause act on the selected one. The whole document is stored once; each environment's worker resolves its own view of it.

No port here

A config describes what the API is, never where it listens. There is no port in akuma.yml: akuma start takes --port for local runs, and a hosted environment is given its own address by the platform.

Common mistakes

Deploying an environment that is not declared

--env must name an environment under environments: (or default):

Error: No environment 'prod' is defined. Available: default, prd.