Skip to main content

Deploying canisters

Beginner
Tutorial

After you have built a canister, you can deploy it to:

  • The local replica where no tokens or cycles are required.

  • The playground on the mainnet, which is a testnet-like sandbox environment. No tokens or cycles are required to deploy and run your canister on the playground, but it will be removed after 20 minutes.

  • The mainnet, designed for production use. This deployment method will cost cycles.

dfx deploy does several processes in the background, including:

Testnets​

Most blockchain networks have separate testnets that allow developers to test their projects in a production-like environment at a significantly lower cost than on the mainnet. Because the execution of canisters on ICP is fairly cheap and canisters can be upgraded once deployed, there is no testnet for ICP.

Developers are encouraged to test their canister smart contracts locally or directly on the mainnet.

However, tools such as ICP Ninja (a web IDE) and the playground (available from the CLI) can be used as testnet-like deployment options. They do not require cycles or tokens to deploy and operate a canister, but they do have limitations and canisters will be automatically removed after 20 minutes.

For most developers, the playground option can be used. For more advanced developers and use cases, there are two possible options for a testnet-like environment:

  • Private testnets: Developers can deploy their own custom instance of the playground on the mainnet, allowing for full customization of the playground's parameters.

  • Synthetic testnets: The dfx named network feature can be used to create custom local networks that can be used for local testing segmented from other projects deployed locally.

Deploying canisters​

Install the IC SDK.
Write a smart contract.
Create your canister. Optional; dfx deploy will execute this step if not already complete.
Compile your canister code into Wasm. Optional; dfx deploy will execute this step if not already complete.
Install the Wasm module into your canister. Optional; dfx deploy will execute this step if not already complete.

Verify you are in your project's directory and the canisters you'd like to deploy are configured in the project's dfx.json file.

  • dfx deploy <canister-name>: Deploy a canister locally. The local replica must be running to deploy a canister locally. Start it with dfx start --background.

  • dfx deploy <canister-name> --network=playground: Deploy a canister on the playground. Deploying a canister on the playground is free, but canisters are temporary and will be removed after 20 minutes.

  • dfx deploy <canister-name> --network=ic: Deploy a canister on the mainnet. Deploying a canister on the mainnet will cost cycles.

  • dfx deploy --network=ic: Deploy all canisters in the project's dfx.json file on the mainnet.

Once a dapp has been deployed to the mainnet, each canister can be accessed via a public URL. This URL can be shared with anyone, allowing them to view and interact with your dapp without you needing to configure domain names, DNS records, or other networking configurations.

You can use the following URL format to access a canister in the web browser:

https://<canister_id>.icp0.io

If you are sharing a link to a frontend (asset) canister, the frontend of the dapp will be displayed.

If you are sharing a link to a backend canisters, the Candid UI will be displayed.

Use a custom Motoko version with dfx deploy​

To use a custom Motoko version with dfx deploy, export the following environment variable that indicates which Motoko base version you'd like dfx to use:

DFX_MOC_PATH="$(vessel bin)/moc" dfx deploy

Setting a canister's init arguments​

You can set a canister's init arguments when the canister is deployed by passing the --argument flag:

dfx deploy <canister-name> --argument "(arg in candid)"

If several arguments should be used, an argument file can be defined with the --argument-file flag instead:

dfx deploy <canister-name> --argument-file file.txt

Alternatively, init arguments can be set in dfx.json in dfx versions v0.17.0 and newer:

dfx.json
"canisters": {
    "hello_backend": {
      "candid": "src/hello_backend/hello_backend.did",
      "package": "hello_backend",
      "type": "rust",
      "init_arg": "(arg in candid)"
    },
 }

If an init argument is set in dfx.json and set with the CLI command, the argument set in the CLI command is used.