Settings

Beginner

Tutorial

Overview

If you have experimented with using the IC SDK by following the tutorials in this section or by cloning examples from the examples repository, you are already familiar with how to build and deploy programs as canisterss. This section provides additional information about the canister lifecycle and how to manage canisters.

Obtaining a canister identifier

Depending on your preferred development workflow, you can obtain a unique identifier for your canister, before or after you have a program ready to compile. For example, if you want to reserve a unique identifier for your canister on a subnet before you have written any code, you can do so by running the dfx canister create command. This command essentially creates an empty canister placeholder into which you can later install your code. The resulting canister will obtain a unique identifier.

To obtain a unique identifier for a canister:

• Step 1: Open a new terminal window or tab on your computer.

• Step 2: Create a new project for the canister you plan to create by running a command similar to the following:

    dfx new YOUR-PROJECT-NAME

  Note that the name you use for the project is also used as the canister name by default.

• Step 3: Change to your new project directory.

• Step 4: Open the dfx.json configuration file and set the host and port for the canister execution environment you want to use (e.g. ICP blockchain).

  If you are using a local deployment, you can skip this step.

  You can also optionally change the names of your canisters or add canister settings to the configuration file if you want to create identifiers for any additional canisters you think you will need before compiling code.

• Step 5: Start the local canister execution environment, if necessary, by running the following command:

    dfx start --clean --background

  In most cases, this step is only necessary if you are running the canisters locally.

  If you were registering canisters to run on a remote execution environment, e.g. ICP blockchain, you would include the --network command-line option to perform tasks on the environment specified under this parameter.

• Step 6: Register unique identifiers for the canisters defined in the dfx.json by running the following command:

    dfx canister create --all

  The command creates the .dfx/local directory and adds the canister_ids.json file to that directory for the project.

Look up a canister ID

All canisters have unique identifiers. You often need to use these identifiers to interact with the canister. For example, if you want to access the frontend canister for a dapp or interact with a service using the Candid web interface, you must specify the appropriate canister identifier.

Because the identifiers are specific to the environment where the canisters are deployed, the files used to store the information are in different directories. For example, identifiers for a canister deployed locally are located in the project’s .dfx/local/canister_ids.json file.

You can look up the canister identifier for any specific canister by running the dfx canister id command. For example, to look up the the canister identifier for the lookup canister deployed on the local canister execution environment, you could run the following command:

dfx canister id lookup

To look up the canister identifier for the same canister deployed on the environment specified by the ic alias, you would run the following command:

dfx canister --network=ic id lookup

Add a wallet for existing canisters

When you are doing local development, creating a new project automatically creates a default wallet for you to use with the canisters in that project. If you want to add a wallet for projects with canisters that you have previously created, you can force dfx to generate one by taking a couple of manual steps.

To add a wallet for use with an existing canister:

• Step 1: Open a terminal and navigate to your project directory.

• Step 2: Stop the local canister execution environment, if necessary, by running the following command:

    dfx stop

• Step 3: Delete the .dfx directory.

• Step 4: Start the local canister execution environment network by running the following command:

    dfx start --clean

Reinstall a canister

During the development cycle, you might want to install, then update your program as you debug and improve it.

In this scenario, you might want to keep the canister identifier you have registered but without preserving any of the canister code or state. For example, your canister might only have test data that you don’t want to keep or you might have decided to change the program altogether. In these scenarios, you may want to reinstall under a canister identifier you used to install a previous program.

To reinstall a canister:

• Step 1: Open a new terminal and navigate to your project directory.

• Step 2: Start the local canister execution environment, if necessary.

  In most cases, this step is only necessary if you are running the canisters locally.

  If you were registering canisters to run on a remote execution environment, e.g. ICP blockchain, you would include the --network command-line option to perform tasks on the environment specified under this parameter.

• Step 3: Verify you have canister identifiers for all of the canisters you want to re-deploy.

• Step 4: Re-deploy all of the canisters by running the following command for every canister:

dfx canister install <canister id or name> --mode reinstall

Note that you can use the reinstall mode to replace any canister, regardless of whether the canister has code or state associated with it.

Set an identity to own a canister

In most cases, a default user identity is created for you automatically the first time you run the dfx canister create command. This default identity consists of the public and private key pair generated for your local user account. Typically, this default identity is also the default owner of all of the projects you create and all of the canisters you deploy. You can, however, proactively create and use identities of your choice to circumvent the default user identity from being used.

As an example, the following scenario illustrates creating a registered_owner identity that is then used to register, build, deploy, and call the pubs project.

To set an identity for a project:

• Step 1: Create a new project by running the following command:

    dfx new project

• Step 2: Change to the project directory by running the following command:

    cd project

• Step 3: Start the local canister execution environment in the background by running the following command:

    dfx start --clean --background

• Step 4: Create a new registered_owner identity by running the following command:

    dfx identity new registered_owner

• Step 5: Set the active user context to use the registered_owner identity by running the following command:

    dfx identity use registered_owner

• Step 6: Register, build, and deploy canisters for the project by running the following commands:

    dfx canister create --all
    dfx build --all
    dfx canister install --all

  These commands run using the registered_owner identity, making that user the owner of the canisters deployed.

• Step 7: Call the greet function from your project's *_backend canister to verify a successful deployment by running the following command:

    dfx canister call project_backend greet '("Sam")'