Developer Resources
Managing Canisters
Learn everything you need to know about managing canister smart contracts on the Internet Computer
Manage Canister Smart Contracts
Managing canisters throughout the entire canister lifecycle
Obtaining canister identifier
Depending on your preferences, you can obtain a canister smart contract identifier either before or after you have a program to compile.
To reserve a unique identifier on a subnet before writing code, run the following command:
This will create an empty canister placeholder. Later on, you can install your code into the empty placeholder.
These are the steps to obtain a unique identifier for your canister:
#1 – New terminal window
Open new terminal window or a new tab on your computer
#2 – Create new project
To create a new project for the canister you want to create, run the following command (replace PROJECT-NAME with the name of your project which is by default used as the canister name as well):
#3 – Change to new project directory
Once you have run the command, you can change to the new project directory.
#4 – Setting the host and port Only for network deployment
To set the host and port for the execution environment of your canister (e.g. the Internet Computer blockchain), open the dfx.json file.
At this stage, you can optionally make changes to the names of your canisters. You can also add canisters settings to your configuration file should you wish to create new identifiers for additional canisters before compiling code.
#5 – Start local execution environment
If necessary, start local canister execution environment via:
Be sure to include the --network command-line option if you want to run your canisters on a remote execution environment such as the Internet Computer blockchain. Adding this option ensures that tasks can be performed in the specified environment.
The command should look as follows:
#6 – Registering unique identifiers
In the last step, you can register unique identifiers for the canisters you have defined in the dfx.json file. To do so, run the following command:
Running this command creates the .dfx/local directory. Within the directory, the canister_ids.json file is being created.
Building canister with local identifier
Before deploying your source code as a canister, be sure to compile your code into a WebAssembly module. You can generate an identifier for your project that is locally defined in case you are just compiling the project for local debugging purposes.
Follow these steps to generate the locally-defined identifier:
#1 – Create project
Create your project with the configuration and program logic you need.
#2 – Start local execution environment
If necessary, start the local canister execution environment via:
For a remote execution environment such as the Internet Computer blockchain, add --network
The command should look as follows:
#3 – Generate hard-coded local identifiers
In the last step, run the following command to generate hard-coded local identifiers for all your canisters defined in dfx.json:
Deploying canister
Once the program is compiled, you can install it in a canister smart contract. You can choose between running the code in a local execution environment or on the IC blockchain.
Follow these steps to deploy your code:
#1 – Open new terminal
Navigate to the directory of your project by opening a new terminal.
#2 – Start local execution environment
If necessary, start the local canister execution environment via:
For a remote execution environment such as the Internet Computer blockchain, add --network
The command should look as follows:
#3 – ID verification
#4 – Deploy
Deploy all canisters via:
Looking up canister identifier
Each canister has a unique identifier. To interact with a canister, you typically need its identifier. The files used for storing the information are located in different directories as the identifiers are specific to the deployment environment.
Run the dfx canister id command to look up the identifier of a specific canister.
Looking up identifier on local execution environment
Looking up identifier on IC environment
Adding wallet for existing canister
When creating a new project in a local development, a default wallet is automatically created. If you have already created a canister in a network deployment, you can force the creation of a wallet with the following steps:
#1 – Navigate to project directory
Open your terminal and navigate to the directory of your project
#2 – Stop local execution environment
If necessary, run the following command to stop the local canister execution environment:
#3 – Delete .dfx directory
#4 – Start local execution environment
Once the .dfx directory is deleted, run the following command to start the local execution environment:
Reinstalling canister
The process of debugging may require you to install and replace your program during the development cycle. In such a case, you may wish to delete the canister’s code or state while keeping the canister identifier.
To reinstall a canister, follow these steps:
#1 – Navigate to project directory
Open your terminal and navigate to the directory of your project
#2 – Start local execution environment
If necessary, start the local canister execution environment via:
For a remote execution environment such as the Internet Computer blockchain, add --network
The command should look as follows:
#3 – ID verification
#4 – Re-deploy
Re-deploy all canisters via:
Setting identity as canister owner
If you run the dfx canister create command for the first time, the system automatically creates a default user identity – in most cases. As a default, the identity contains both the public and private key pair for your local user account. If you create projects and deploy canisters, the default identity will also be set as the default owner of these. To circumvent this, you can proactively create identities of your own choice.
To illustrate how this works, we will be creating the identity for registered_owner that is used to register, create, deploy, and call the pubs project. Here’s how you can set an identity for your project:
#1 – Create new project via the following command
#2 – Switch to the project directory
#3 – Start local canister execution environment
#4 – Create new identity
#5 – Set active user context to use the new identity
#6 – Register, build, and deploy canisters
You’ve set the active user context to use the registered_owner in step #5. Therefore, these commands are using this new identity, making it the owner of the deployed canisters.
#7 – Verify successful deployment
Lastly, verify if the canister has been successfully deployed by calling the greet function.
Managing running state of canister
By default, canisters are placed in the Running state. But there may be cases in which you may want to temporarily or even permanently stop your canister. Such cases include:
- Stopping the canister before you upgrade it
- Ensuring proper handling of messages that are in progress. Messages will either run to completion or are rolled back
- Clearing a canister’s message queue cleanly before deleting it
Checking the current status of all canisters in local execution environment
Running the command returns output similar to this (if there are canisters currently running):
Stopping currently running canisters
Running the command returns output similar to the following:
Restarting a canister
Running the command returns output similar to the following:
Upgrading a canister
- Reinstalling a canister preserves its identifier but not its state
- Upgrading a canister preserves the state and allows you to change the code.
Follow these steps to upgrade your canister:
#1 – Navigate to project directory
Open your terminal and navigate to the directory of your project
#2 – Start local execution environment
If necessary, start the local canister execution environment via:
For a remote execution environment such as the Internet Computer blockchain, add --network
The command should look as follows:
#3 – Verify canister identifiers
Make sure to verify all the canisters you want to upgrade have identifiers. In the variable declaration, use the stable keyword to help your program identify variables for which to maintain state.
#4 – Upgrade all canisters
Deleting canister
The dfx canister delete command enables you to permanently delete canisters. You can decide if you want to delete only one specific canister or all canisters of a specific project running on a given deployment.
Follow these steps to delete all the canisters of your project:
#1 – Navigate to project directory
Open your terminal and navigate to the directory of your project
#2 – Start local execution environment
If necessary, start the local canister execution environment via:
For a remote execution environment such as the Internet Computer blockchain, add --network
The command should look as follows:
