Tips for deploying to a specific subnet

Developers
1

Hi everyone!

We have fielded this question a few times from developers who are either looking to a) make their first deployment on a specific subnet or b) “move” to another subnet with open capacity, so I thought I would post to share the steps I have personally used in the past. Some background for those who have not yet encountered this, it is not currently possible to target a specific subnet, and so any new canisters that are created are assigned to a random subnet. Once you have a cycles wallet set up, any future canisters will be deployed to the subnet where your cycles wallet is deployed. For this reason, sometimes it is desired to get a new cycles wallet set up on a separate subnet in order to start deploying canisters to a different subnet.

A few very important disclaimers:

  • If you already have a canister / dapp with active users who have authenticated using II, this process is not for you! This process involves creating a new canister on a new subnet, which will break auth for all of your users. The DFINITY team is working on a more robust migration mechanism for dapps / canisters with existing traction and users authenticated through II, so please stay tuned.
  • If you have an existing canister / dapp with a large state, please note that these steps below do NOT take into consideration a backup and migration of that state. Re-deploying a new canister on a new subnet will result in a new instance of your canister / dapp, so please take any necessary precautions to back up your state first before attempting a true migration (vs. just a fresh deployment).
  • This process is ideal for new projects that are deploying for the first time, canisters you may only be using for testing, expanding your dapp to more canisters (e.g. storing assets), etc.
  • The below steps work as of today for this process, but please note this is subject to change with any updates to dfx.
  1. Make sure that the dfx identity you’re using isn’t already tied to a previously created cycles wallet. If needed, create a new identity using dfx identity new <identity-name>.
  2. Make sure the ledger account associated with this new identity has some ICP. To find your account ID, use dfx ledger --network ic account-id. You can send ICP to that account from another ledger account, Coinbase wallet, etc.
  3. Once you have ICP in the account associated with the appropriate identity, run dfx ledger --network ic create-canister <principal ID> --icp 1. Make sure this principal ID is the one associated with the identity you’re using (the one without a cycles wallet). You can use less than 1 ICP, but I find this is helpful just in case you need those cycles.
  4. The output will look something like this:

Transfer sent at BlockHeight: 3335010
Canister created with id: "y4io3-myaaa-aaaag-aaeka-cai"

You can then search for that canister ID on the ICA dashboard. This will tell you which subnet your new canister has landed on and you can check the subnet stats, how many canisters are deployed, remaining capacity, etc.

  1. If you want to try for another subnet, repeat steps 3-4 until your canister lands on the desired subnet.
  2. Once you have found the subnet you would like to deploy the cycles wallet to, run dfx identity --network ic deploy-wallet <canister-id>. Make sure the canister id is that of the newly created canister on the desired subnet. Be careful not to use the set-wallet command instead of deploy-wallet - this will set the wallet without installing the wasm module, and it can be difficult to reinstall after it is set (involves deleting some things in the wallets.json file). The SDK team is aware of this issue and is working on some fixes to prevent devs from getting into this situation.
  3. From there, your cycles wallet will be created and you can add/remove controllers as needed. Any canisters you create will now be created via this cycles wallet on the new subnet.
  4. For any canisters that landed on other subnets, you can later install cycles wallets on those canisters and send any remaining cycles to the new cycles wallet to avoid waste :slight_smile:

Please note this is just one way to do this, but it’s something that has worked well for me so far. There is another process here in the docs that I have not tried but might also work (which involves creating from another cycles wallet vs. creating a new canister from scratch using ICP). Some of the above steps are also documented here and here as well.

Hope this helps, enjoy your new subnet! :hugs:

13 Likes