managing-environments.md

title	Managing Environments
description	Configure and use dev, staging, and production environments to deploy independent canister instances with different settings.

Environments allow you to deploy multiple instances of a set of canisters to the same network, with each set having independent settings. This guide covers setting up development, staging, and production environments.

Understanding Environments

An environment combines:

• A network to deploy to
• A set of canisters to deploy
• Settings specific to that environment

Two implicit environments are always available:

• local — Uses the local managed network (default)
• ic — Uses the IC mainnet

Basic Environment Configuration

Add environments to your icp.yaml:

canisters:
  - name: frontend
    build:
      # ... build steps
  - name: backend
    build:
      # ... build steps

environments:
  - name: staging
    network: ic
    canisters: [frontend, backend]

  - name: production
    network: ic
    canisters: [frontend, backend]

Environment-Specific Settings

Override canister settings per environment:

environments:
  - name: staging
    network: ic
    canisters: [frontend, backend]
    settings:
      backend:
        compute_allocation: 5
        environment_variables:
          LOG_LEVEL: "debug"

  - name: production
    network: ic
    canisters: [frontend, backend]
    settings:
      backend:
        compute_allocation: 20
        freezing_threshold: 90d
        environment_variables:
          LOG_LEVEL: "error"

Deploying to Environments

Deploy to a specific environment:

# Local development (default)
icp deploy

# Staging
icp deploy --environment staging

# Production
icp deploy --environment production

# IC mainnet (using implicit ic environment)
icp deploy -e ic

Environment-Specific Install Args

Provide different initialization arguments per environment:

canisters:
  - name: backend
    build:
      # ... build steps
    init_args: "(record { mode = \"production\" })"

environments:
  - name: staging
    network: ic
    canisters: [backend]
    init_args:
      backend: "(record { mode = \"staging\" })"

upgrade_args works the same way, and is used in place of init_args when the canister is upgraded rather than installed:

canisters:
  - name: backend
    build:
      # ... build steps
    init_args: "(variant { init = record { mode = \"production\" } })"
    upgrade_args: "(variant { upgrade })"

environments:
  - name: staging
    network: ic
    canisters: [backend]
    upgrade_args:
      backend: "(variant { upgrade_staging })"

A canister with no upgrade_args — in its own manifest or in the environment — is upgraded with its init_args.

Viewing Environment Configuration

See all configured environments:

icp environment list

View the effective project configuration:

icp project show

This shows all environments and their settings.

Working with Canister IDs

Each environment maintains separate canister IDs. The storage location depends on network type:

• Managed networks (local): .icp/cache/mappings/<environment>.ids.json
• Connected networks (IC mainnet): .icp/data/mappings/<environment>.ids.json

List canisters configured for an environment:

icp canister list --environment staging

This shows the network status of the canisters in that environment:

icp canister status --environment staging

Example: Full Multi-Environment Setup

canisters:
  - name: frontend
    build:
      steps:
        - type: script
          commands:
            - npm run build
    sync:
      steps:
        - type: plugin
          path: ./plugins/upload-assets.wasm
          files:
            assets: dist

  - name: backend
    build:
      steps:
        - type: script
          commands:
            - cargo build --target wasm32-unknown-unknown --release
            - |-
              TARGET_DIR=$(cargo metadata --format-version 1 --no-deps | sed -n 's/.*"target_directory":"\([^"]*\)".*/\1/p')
              cp "${TARGET_DIR}/wasm32-unknown-unknown/release/backend.wasm" "$ICP_WASM_OUTPUT_PATH"

environments:
  - name: staging
    network: ic
    canisters: [frontend, backend]
    settings:
      frontend:
        memory_allocation: 2gib
      backend:
        compute_allocation: 5
        reserved_cycles_limit: 5t
        environment_variables:
          API_ENV: "staging"

  - name: production
    network: ic
    canisters: [frontend, backend]
    settings:
      frontend:
        memory_allocation: 4gib
        freezing_threshold: 90d
      backend:
        compute_allocation: 20
        reserved_cycles_limit: 50t
        freezing_threshold: 90d
        environment_variables:
          API_ENV: "production"

Deployment Workflow

A typical workflow:

# 1. Develop locally
icp network start -d
icp build && icp deploy
# ... test changes ...

# 2. Deploy to staging
icp deploy --environment staging
# ... verify on staging ...

# 3. Deploy to production
icp deploy --environment production

Next Steps

• Environments and Networks — Understand how environments work

Browse all documentation →