Skip to main content

1.5 Deploying canisters

Beginner
Tutorial

Overview

Now that you have some cycles to pay for your canister's resources, you can deploy your dapp on the mainnet. When a canister is deployed to the mainnet, it's code will be hosted on the nodes that make up one of the mainnet's subnets. The canister will be hosted on these nodes until it is manually uninstalled by the developer, or until it runs out of cycles and is uninstalled automatically.

Once a dapp is deployed on the mainnet, it can be accessed from the canister's public URL by end-users and can communicate with other canisters that are deployed on the mainnet.

Prerequisites

Before you start, verify that you have set up your developer environment according to the instructions in 0.3 Developer environment setup.

You will be building off of the previous two modules, 1.3 Developing your first dapp and 1.4 Acquiring and using cycles. You will need to have followed along and completed the steps outlined in these modules to complete this tutorial.

Deploying to the mainnet

To deploy your dapp to the mainnet, first assure that your terminal window is open and you've navigated into the directory of your poll dapp that you created in module 1.3 Developing your first dapp.

Then, assure that all necessary packages are installed for the project's frontend with the command:

npm install

Now it's time to register, build, and deploy your dapp. First, let's check to make sure you have an active connection to the mainnet. Run the command:

dfx ping ic

A successful connection to the mainnet will return an output such as:

{
"certified_height": 57374997 "ic_api_version": "0.18.0" "impl_hash": "d5896681ceac74c83c9473654de75214d5079193294ade3775e89a81270fd0cf" "impl_version": "f8f59f896499f2fef394d8321116f83351c59aa8" "replica_health_status": "healthy" "root_key": [48, 129, 130, 48, 29, 6, 13, 43, 6, 1, 4, 1, 130, 220, 124, 5, 3, 1, 2, 1, 6, 12, 43, 6, 1, 4, 1, 130, 220, 124, 5, 3, 2, 1, 3, 97, 0, 129, 76, 14, 110, 199, 31, 171, 88, 59, 8, 189, 129, 55, 60, 37, 92, 60, 55, 27, 46, 132, 134, 60, 152, 164, 241, 224, 139, 116, 35, 93, 20, 251, 93, 156, 12, 213, 70, 217, 104, 95, 145, 58, 12, 11, 44, 197, 52, 21, 131, 191, 75, 67, 146, 228, 103, 219, 150, 214, 91, 155, 180, 203, 113, 113, 18, 248, 71, 46, 13, 90, 77, 20, 80, 95, 253, 116, 132, 176, 18, 145, 9, 28, 95, 135, 185, 136, 131, 70, 63, 152, 9, 26, 11, 170, 174]
}

Now, you can deploy your dapp to the mainnet by running the following command:

dfx deploy --network ic

In this command, the --network flag specifies which network the dapp should be deployed on. Other options for this flag are --network local and --network playground. This tutorial series covered these in module 1.1: exploring a live demo.

Using the flag --network ic is required to deploy your dapp on the mainnet. If this flag is not included, your dapp will only be deployed locally by default.

This command doesn't include a canister name, meaning it will automatically deploy all canisters that are specified in the dfx.json file. You can specify a single canister to be deployed by including the canister's name in the command, such as:

dfx deploy poll_backend --network ic

You want to deploy both the poll_backend and poll_frontend canisters since they work together to create your poll dapp, so the dfx deploy --network ic command should be used for this tutorial.

The output of this command will include information about what actions are happening. For example, the output should resemble the following:

Deploying all canisters.
Creating canisters...
Creating canister "poll_backend"...
"poll_backend" canister created on network "ic" with canister id: "5o6tz-saaaa-aaaaa-qaacq-cai"
Creating canister "poll_frontend"...
"poll_frontend" canister created on network "ic" with canister id: "5h5yf-eiaaa-aaaaa-qaada-cai"
Building canisters...
Building frontend...
Installing canisters...
Installing code for canister poll_backend, with canister_id 5o6tz-saaaa-aaaaa-qaacq-cai
Installing code for canister poll_frontend, with canister_id 5h5yf-eiaaa-aaaaa-qaada-cai
Authorizing our identity (default) to the asset canister...
Uploading assets to asset canister...
/index.html 1/1 (472 bytes)
/index.html (gzip) 1/1 (314 bytes)
/index.js 1/1 (260215 bytes)
/index.js (gzip) 1/1 (87776 bytes)
/main.css 1/1 (484 bytes)
/main.css (gzip) 1/1 (263 bytes)
/sample-asset.txt 1/1 (24 bytes)
/logo.png 1/1 (25397 bytes)
/index.js.map 1/1 (842511 bytes)
/index.js.map (gzip) 1/1 (228404 bytes)
/index.js.LICENSE.txt 1/1 (499 bytes)
/index.js.LICENSE.txt (gzip) 1/1 (285 bytes)
Deployed canisters.

If you manually converted ICP tokens into cycles, and your cycles balance doesn't contain enough cycles to complete this deployment, you can convert more ICP into cycles with the command:

dfx cycles convert 1.005 --network ic

This command converts an additional 1.005 ICP tokens to cycles.

If you used the free cycles coupon, this step is not applicable.

Now, let's use your dapp! To access the dapp's frontend, first you need to get the canister's URL. To get this, run the command:

dfx canister id poll_frontend --network ic

This command will return the canister's URL, which should look like this:

https://5h5yf-eiaaa-aaaaa-qaada-cai.icp0.io

If you open this URL in your web browser, you will see the same poll dapp frontend that you saw when you deployed it locally. The only difference is that now your dapp is hosted 100% on-chain, does not rely on your local replica to keep running, and you can send this URL to your friends and get them to vote on your poll!

To avoid burning through your cycles, once you are finished with this tutorial consider stopping your project's canisters with the dfx canister stop command.

Need help?

Did you get stuck somewhere in this tutorial, or feel like you need additional help understanding some of the concepts? The ICP community has several resources available for developers, like working groups and bootcamps, along with our Discord community, forum, and events such as hackathons. Here are a few to check out:

Next steps

Now that you have canisters running on the mainnet, the next steps are to learn how you can manage these canisters, such as how to upgrade them or delete them.