Deploying and Interacting with our Canister

Having completed the coding of our canister, it's now time to deploy and interact with it.

Starting the Local Internet Computer

The first step is to initialize our local Internet Computer replica, which is essentially an instance of the Internet Computer blockchain where our canister will run. We'll start this replica in the background to allow for other operations. This can be done by executing the following command in your terminal:

shellDownloadCopy code
dfx start --background

Upon successful execution, your terminal will display an output similar to the one below. This output confirms that a local instance of the Internet Computer is running, and it also provides a link to a dashboard where you can monitor the status of your local instance.

shellDownloadCopy code
Running dfx start for version 0.14.0
Using the default definition for the 'local' shared network because /Users/<username>/.config/dfx/networks.json does not exist.
Dashboard: http://localhost:49846/_/dashboard

In this output, the URL for the dashboard (<http://localhost:49846/_/dashboard>) will be particularly helpful for debugging and observing the activity of your local replica.

IMPORTANT NOTE StableBTreeMap, which is the data structure we use for messageStorage, has certain constraints that you need to be aware of. Specifically, once a StableBTreeMap is initialized, its configuration becomes immutable. This means that you cannot make changes to aspects such as the data types or sizes of the keys or values.

If you need to make any changes to these elements of the StableBTreeMap, you will need to restart your local replica with the --clean flag. The --clean flag ensures that the replica is started afresh, allowing for the changes in configuration to take effect.

Here's how you can do it:

shellDownloadCopy code
dfx start --background --clean

Remember, only use the --clean flag if you have made changes to the configuration of your StableBTreeMap. If no changes have been made, a regular start of the local replica (i.e., without the --clean flag) will suffice.

Deploying the Canister

Next, we will compile our canister code and install it on the local network using the dfx deploy command:

shellDownloadCopy code
dfx deploy

The dfx deploy command is a convenient way to register, build, and deploy a canister on the Internet Computer network. By default, it targets all canisters defined in the project's dfx.json configuration file. This command combines the following steps into one:

1. Creating the canister (dfx canister create --all)
2. Building the canister (dfx build)
3. Installing the canister (dfx canister install --all)

Executing the dfx deploy command should result in an output similar to:

shellDownloadCopy code
Creating the "default" identity.
WARNING: The "default" identity is not stored securely. Do not use it to control a lot of cycles/ICP.
To create a more secure identity, create and use an identity that is protected by a password using the following commands:
    dfx identity new <my-secure-identity-name> # creates a password protected identity
    dfx identity use <my-secure-identity-name> # uses this identity by default
 
  - generating new key at /Users/alice/.config/dfx/identity/default/identity.pem
Your seed phrase:
...

Note: If this is your first time running the dfx deploy command, it may take a moment to register, build, and deploy your application. Take this time to relax as the system does its work.

Once the command completes, you should see a message indicating the successful deployment of your canisters. The output will include URLs for interacting with your backend canister through the Candid interface. For example:

shellDownloadCopy code
Deployed canisters.
URLs:
  Backend canister via Candid interface:
    message_board: http://127.0.0.1:4943/?canisterId=bd3sg-teaaa-aaaaa-qaaba-cai&id=bkyz2-fmaaa-aaaaa-qaaaq-cai

The provided URL (in this case: http://127.0.0.1:4943/?canisterId=bd3sg-teaaa-aaaaa-qaaba-cai&id=bkyz2-fmaaa-aaaaa-qaaaq-cai) is the endpoint for your message_board canister. This URL links to a Candid interface, which provides a web-based interface for interacting with your canister's methods.

You can view a GIF illustrating this process:

Interacting with our canister

There are two primary ways to interact with our canister: through the command line interface (CLI) or the web interface. We'll begin with the CLI.

Interacting with our canister through the CLI

To interact with our canister through the CLI, we'll be using the dfx canister call command. This command allows us to invoke functions on our canister from the terminal.

1. Adding a message First, let's invoke the addMessage function from our canister file, which we created earlier. This function will add a message to our canister. Execute the following command in your terminal:

shellDownloadCopy code
dfx canister call message_board addMessage '(record {"title"= "Welcome"; "body"= "Hello World"; "attachmentURL"= "url/path/to/some/photo/attachment"})'

If the function call is successful, you should receive a response similar to this:

javascriptDownloadCopy code
(
  variant {
    Ok = record {
      id = "79daba82-18ce-4f69-afa1-7b3389368d1f";
      attachmentURL = "url/path/to/some/photo/attachment";
      title = "Welcome";
      updatedAt = null;
      body = "Hello World";
      createdAt = 1_685_568_853_915_736_000 : nat64;
    }
  },
)

This output indicates that the addMessage function has successfully added a message to your canister. The message includes a unique identifier, attachment URL, title, body, and creation timestamp. The updatedAt field remains null because the message has not been updated since it was created.

2. Retrieving a single message To retrieve a single message, invoke the getMessage function. Replace 79daba82-18ce-4f69-afa1-7b3389368d1f with the unique ID of the message you wish to retrieve. Here's the command:

shDownloadCopy code
 canister call message_board getMessage '("79daba82-18ce-4f69-afa1-7b3389368d1f")'

3. Updating a message To update a message, use the updateMessage function. Replace 79daba82-18ce-4f69-afa1-7b3389368d1f with the unique ID of the message you wish to update. Here's the command:

shDownloadCopy code
dfx canister call message_board updateMessage '("79daba82-18ce-4f69-afa1-7b3389368d1f", record {"title"= "new title"; "body"= "new message"; "attachmentURL"= "url/path/to/some/photo/attachment"})'

4. Retrieving messages To retrieve all messages, invoke the getMessages function. In this case, we're not passing any argument to the function. Here's the command:

shDownloadCopy code
 canister call message_board getMessages '()'

5. Deleting a message To delete a message, use the deleteMessage function. Replace 79daba82-18ce-4f69-afa1-7b3389368d1f with the unique ID of the message you wish to delete. Here's the command:

shDownloadCopy code
 canister call message_board deleteMessage '("79daba82-18ce-4f69-afa1-7b3389368d1f")'

Try for yourself, to add, retrieve, update, and delete messages using the CLI.

Now that we've covered the CLI, let's move on to the web interface.

2. Getting a message with the web interface Now we are using the web interface to get the message we just created. Let's invoke the getMessage function from our canister file.

To view the message we just added, we can make use of the candid interface that was generated to us when we ran the "dfx deploy" command.

It should look something like this:

shellDownloadCopy code
http://127.0.0.1:4943/?canisterId=bd3sg-teaaa-aaaaa-qaaba-cai&id=bkyz2-fmaaa-aaaaa-qaaaq-cai

Note: In Codespaces, the web interface might sometimes not be displayed correctly. In that case, you will need to use the CLI to interact with your canister.

In the interface, click on the getMessage function. Then, enter the ID of the message you wish to retrieve. In this instance, we'll be retrieving the message we just created, hence we'll need to input the ID that we received from the addMessage function response. Please note, your message ID will differ from the example given here.

After entering the ID, click on the Call button. If done correctly, you should receive a response similar to this:

javascriptDownloadCopy code
(
  variant {
    Ok = record {
      id = "79daba82-18ce-4f69-afa1-7b3389368d1f";
      attachmentURL = "url/path/to/some/photo/attachment";
      title = "message list";
      updatedAt = null;
      body = "some important things";
      createdAt = 1_685_568_853_915_736_000 : nat64;
    }
  },
)

You can view a GIF illustrating this process of interacting with the web interface:

Now you can use the web interface to interact with the same functions we used in the CLI.

To conclude your work session, you can stop your local Azle replica by executing the following command in your terminal:

shellDownloadCopy code
dfx stop

This command will shut down your local replica. Remember to always stop your local replica when you're done working to free up system resources."