Skip to main content

Staging environment

Intermediate
Tutorial

Overview​

Having a separate deployment environment available where features can be end-to-end tested before they get deployed to the production environment can be helpful. While local deployments mirror the live mainnet as closely as possible, it is not the same. The local instance only runs as a single subnet. If you want to test canisters of two different subnets connecting to each other, you cannot do this locally. Other benefits of using a staging environment include being able to test an integration with other services, deployment workflows, and estimating costs before setting a feature live.

Setting up a staging environment​

In a staging environment it is possible to run any dfx command that would otherwise take --network ic but using --network myStaging instead. myStaging can be replaced with any other name, except the three reserved ones: ic, local, and playground.

Networks are defined in two ways: assumed and explicitly configured. dfx only contains the ic network as an assumed environment. The flag --network ic can be used to run any command on the mainnet.

All other networks are explicitly configured in dfx.json. The "networks" section should contain at least the local network, which gets chosen by default if no other network is specified with the --network flag.

Network definition​

To add a staging network named myStaging to dfx.json, add this code under "networks" in your dfx.json:

"myStaging": {
    "providers": [
        "https://icp0.io"
    ],
    "type": "persistent"
}

This value for "providers" tells dfx where to connect to the network. It is identical to the one in the hard-coded ic network. The type persistent tells dfx that the canisters on this network will stay there and the canister identifiers will be saved in the canister_ids.json file.

Configuring a wallet​

If you are using a cycles wallet, the cycles wallet for each network is stored separately. The newly created myStaging network has no wallet configured yet.

Please note that the cycles wallet will be removed from dfx in a future release.

It is recommended to use the cycles ledger instead.

To use the same cycles wallet as on the main ic network, first make sure the correct identity is set by running the command:

dfx identity use <identity name>

Then, read the ic network's currently configured wallet using:

dfx identity get-wallet --network ic

Set the wallet for the newly defined network with the command:

dfx identity set-wallet <wallet id> --network myStaging

These commands can be used together, such as:

dfx identity set-wallet "$(dfx identity get-wallet --network ic)" --network myStaging

If you prefer to use a separate cycles wallet for the staging environment, follow the instructions in the step 'Creating a cycles wallet' in the deploying to the mainnet guide.