8: Deploy and manage canisters from the CLI

Beginner

Tutorial

Now that you have canisters deployed from the CLI, it's important to learn how to manage and maintain those canisters. Basic canister management includes obtaining information about a canister, adding an identity as a controller of a canister, topping up a canister, starting and stopping a canister, and deleting a canister.

Canister information

Obtaining a canister's ID

Each canister has a unique identifier that can be used to interact with the canister. These unique IDs can be used to access the canister's frontend or Candid UI in a web browser. Having a canister's ID is also important for executing management functions of the canister, such as setting ownership for the canister.

To get the canister ID of the canister that's been deployed on the mainnet, use the command:

dfx canister id hello_world_backend --network ic

If you want to get the canister ID for a locally deployed canister, simply omit the --network ic flag, such as:

dfx canister id hello_world_backend

Obtaining canister details

To obtain information about the canister, such as the canister's controller(s) and the Wasm module hash, use the command:

dfx canister info hello_world_backend

Access control

Adding an identity as a controller of a canister

To add another identity as an additional controller of the canister, first, create a new identity:

dfx identity new ControllerExample

Then, get the principal value for this new identity with the command:

dfx identity use ControllerExample
dfx identity get-principal

Then, use the dfx canister update-settings command to add the returned principal to be a controller of your hello_world_backend canister, but first, you need to switch back to your previously created identity, since only existing controllers can add new controllers:

dfx identity use IDENTITY_NAME

Then, use the dfx canister update-settings command:

dfx canister update-settings hello_world_backend --add-controller PRINCIPAL_ID

Removing an identity as a controller of a canister

You can remove this principal with the command:

dfx canister update-settings hello_world_backend --remove-controller PRINCIPAL_ID

Alternatively, you can use the --set-controller flag instead of the --add-controller flag. If any controllers are set using the --set-controller flag, any other existing controllers will be removed. For example, re-run the command above, but use the --set-controller flag instead:

dfx canister update-settings hello_world_backend --set-controller PRINCIPAL_ID

Viewing the running state of a canister

Once a canister has been deployed, it can receive and process requests from other canisters or end users and is in a Running state. If a canister needs to be temporarily or permanently stopped, such as before it can be upgraded, it must be stopped to ensure proper message handling. Stopping a canister is also a requirement if the canister is going to be deleted.

To check the current state of all canisters, you can use the command:

dfx canister status --network ic --all

Or, you can check the status of a single canister by specifying its name, such as:

dfx canister status hello_world_backend --network ic

The output of the command will resemble the following:

Canister status call result for hello_world_backend.
Status: Running
Controllers: lalyb-uhvmt-p7ubs-u5t7l-hce6v-lp7c5-dlmj5-wi2gc-depab-wtgi3-pae
Memory allocation: 0
Compute allocation: 0
Freezing threshold: 2_592_000
Memory Size: Nat(2363181)
Balance: 3_100_000_000_000 Cycles
Module hash: 0xf8680eb74022a1079012b7e9c644d1156580002a6126305791811533d3fd6f17

Stopping a canister

To stop a single canister, run the command:

dfx canister stop hello_world_backend --network ic

Or, to stop all canisters, use the command:

dfx canister stop --network ic --all

Starting a canister

Then to start the canister again, run the command:

dfx canister start --network ic --all

Cycles management

Checking the cycles balance of a canister

To check a canister's cycles balance, you must be the controller of the canister. The cycles balance can be seen in the output of the dfx canister status command, such as:

dfx canister status hello_world_backend --network ic

The output will resemble the following, where the value Balance refers to the cycles balance:

Canister status call result for hello_world_backend.
Status: Stopped
Controllers: lalyb-uhvmt-p7ubs-u5t7l-hce6v-lp7c5-dlmj5-wi2gc-depab-wtgi3-pae
Memory allocation: 0
Compute allocation: 0
Freezing threshold: 2_592_000
Memory Size: Nat(2363181)
Balance: 3_100_000_000_000 Cycles
Module hash: 0xf8680eb74022a1079012b7e9c644d1156580002a6126305791811533d3fd6f17

Topping up a canister with cycles

Depositing cycles into a canister's cycles balance is known as 'topping up' the canister's balance. For production canisters, which are consistently using cycles over time to pay for the canister's resources, topping up the canister is required for routine maintenance.

While you must be a canister's controller in order to view the cycles balance of the canister, anyone can top up a canister.

There are a few ways to top up a canister:

• Using ICP in your account.
• Using the cycles ledger.
• Using the NNS dapp web UI.
• Using a fiat option through Cycle.express.
• Using a third-party service such as CycleOps. For more information on using a third-party service for cycles management, please see here.

Using ICP

If you currently have a balance of ICP tokens within your dfx ledger account ID, you can use the dfx ledger top-up command to automatically convert that ICP into cycles and deposit it into the specified canister, for example:

dfx ledger top-up hello_world_backend --amount 2.7 --network ic

Using the cycles ledger

If you have already converted some ICP into cycles, you can send cycles to the canister with the dfx cycles top-up command, such as:

dfx cycles top-up `AMOUNT` `CANISTER_ID` --network ic

Getting cycles back from a canister

To withdraw cycles from a canister, the canister must be deleted. The cycles will be returned to the canister's principal controller.

You can stop and delete the canister with the commands:

dfx canister stop hello_world_backend --network ic
dfx canister delete hello_world_backend --network ic

The output of the dfx canister delete command will return information regarding the cycles withdrawn:

Beginning withdrawal of cycles to canister hello_world_backend; on failure, try --no-wallet --no-withdrawal.
Setting the controller to identity principal.
Installing temporary wallet in canister hello_world_backend to enable transfer of cycles.
Attempting to transfer 3089393970000 cycles to canister jqylk-byaaa-aaaal-qbymq-cai.
Successfully withdrew 3089393970000 cycles.
Deleting canister hello_world_backend, with canister_id jqylk-byaaa-aaaal-qbymq-cai

To confirm that the cycles were withdrawn properly, check your cycles balance with dfx cycles balance.

Setting the canister's freezing threshold

A canister's freezing threshold is a value defined in seconds, which is used to calculate how many cycles a canister must retain in its cycles balance. This calculation is based on the canister's memory consumption. The default freezing threshold value is 2_592_000s, which corresponds to 30 days.

The freezing threshold is important because if a canister runs out of cycles, it will be uninstalled. The freezing threshold protects it from deletion, since if the cycles balance dips below the threshold, the canister will stop processing any new requests; however, it will continue to reply to existing requests.

To set a freezing threshold for the 'hello_world_backend` canister, use the command:

dfx canister update-settings hello_world_backend --freezing-threshold 3472000

Then, you can confirm that this threshold has been set by running the dfx canister status hello_world_backend --network ic command again:

Canister status call result for hello_world_backend.
Status: Stopped
Controllers: lalyb-uhvmt-p7ubs-u5t7l-hce6v-lp7c5-dlmj5-wi2gc-depab-wtgi3-pae
Memory allocation: 0
Compute allocation: 0
Freezing threshold: 3_472_000
Memory Size: Nat(2363181)
Balance: 3_100_000_000_000 Cycles
Module hash: 0xf8680eb74022a1079012b7e9c644d1156580002a6126305791811533d3fd6f17

The values returned in this output refer to the following:

• Status: The canister's current status, such as Running, Stopping, or Stopped.
• Controllers: The principal IDs of the canister's configured controllers. Controllers are able to perform operations such as deploying or stopping a canister.
• Memory allocation: The current amount of memory allocated by the canister.
• Compute allocation: The current amount of compute resources allocated by the canister.
• Freezing threshold: The cycles freezing threshold, defined in seconds, indicates when the IC estimates that the canister would be depleted of cycles before freezing_threshold seconds pass. This is estimated using the canister's current cost for storage and the canister's current size.
• Memory size: The size of the memory used by the canister.
• Balance: The canister's current cycles balance.
• Module hash: The canister's Wasm module hash.

Deleting a canister

To delete a single canister, first you need to stop the canister with the command:

dfx canister frontend --network ic stop

Then you can run the command:

dfx canister delete frontend --network ic

When a canister is deleted, the canister's code, state, and canister ID are removed. Canisters must be stopped before they can be deleted. Alternatively, all canisters for a project can be deleted with the commands:

dfx canister --network ic stop --all
dfx canister --network ic delete --all