Skip to main content

Deploy

Beginner
Launching dapp

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

  • The local network created by dfx where cycles are fabricated.

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

  • A custom local or playground network.

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

Install the IC SDK.
Write code.
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. , Then deploy your canisters using the dfx deploy command:

  • 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.

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

  • 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 canister, the frontend of the dapp will be displayed.

If you are sharing a link to a backend canister, 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.

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 canisters locally or directly on the mainnet.

However, tools such as ICP Ninja (a web IDE) and the playground environment (available from the CLI) can be used as testnet-like deployment options. They do not require cycles 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:

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

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