Skip to main content

1.1 Exploring a live demo

Beginner
Tutorial

Overview​

In the previous segment of our developer ladder, introduction to dfx, you created a new dfx project using the default 'Hello, world' template and looked into the project's structure and code. However, you didn't build or deploy the canister.

In this tutorial, you'll deploy the hello_world_backend canister from 0.6: Introduction to dfx to the Motoko playground.

What is the playground?​

The playground is a development environment that hosts a 'canister pool' that canisters can be deployed to. When canisters are deployed to the playground, they temporarily borrow resources from the pool and are allotted a small amount of cycles that can be used during the canister's deployment.

Deploying to the playground is ICP's equivalent of deploying to a testnet network.

Canisters deployed to the playground can run for 20 minutes; after 20 minutes, the canister will be uninstalled and the resources borrowed are returned to the playground's canister pool.

The playground is a great way to be able to deploy a canister quickly for short, small-scale testing, or just to get familiar with the deployment process and how to interact with a canister without needing to complete additional deployment steps, such as acquiring cycles.

Since the playground is designed for testing purposes, there are several restrictions imposed on canisters that have been deployed to the playground that you should be aware of. These restrictions are:

  • Cycle transfer instructions are silently ignored; you cannot transfer cycles to or from your canister on the playground. This means that you cannot use functions such as HTTPS outcalls or threshold ECDSA, since these functions require attached cycles.
  • Wasm files can't be gzipped.
  • Wasm files for deployed canisters will be analyzed to remove any potentially expensive or malicious operations.
  • Canisters can use at most 1GB of memory.
  • Canisters can call the management canister to manage itself without being the controller.
  • Deployed canisters expire after 20 minutes.

dfx deploy --playground​

Using the dfx command dfx deploy --playground, canisters can be deployed directly from the CLI to the playground.

First, let's take a look at how to use this command to deploy our canister. Then you'll explore how you can interact with that canister once it has been deployed. This will act as a live demo for you to explore and use to gain an understanding of the deployment and interaction process.

Prerequisites​

Before you start, verify that you have set up your developer environment according to the instructions in 0.3: Developer environment setup.

This example works with the canister previously created in the 0.6: Introduction to dfx module. It is recommended to complete that module before beginning the steps outlined here.

Deploying to the playground using dfx​

dfx deploy --playground is available in dfx versions v0.15.1 and above.

To deploy a canister to the playground network, first open a terminal window if you do not already have one open.

Then, navigate into the project that you created in the 0.6: Introduction to dfx module. You can use a command such as:

cd developer_journey/hello_world

For more information on file system navigation using the CLI, check out the documentation on the cd command.

For a review on the project's structure and our main.mo source code file, you can review the 0.6: Introduction to dfx module.

Before you can deploy the canister, you need to start the local canister execution environment. To do this, run the command:

dfx start --clean --background

This command starts the local replica in the background. The --clean flag removes any orphan background processes or canister IDs that might cause conflicts in your environment. It is good practice to use this flag when starting dfx, since it can help prevent any issues if you forget to use dfx stop when moving between projects, or if you have processes running in another terminal that you forgot about.

Without the --background flag, the output of the execution environment will take over the terminal window and you would need to open a second terminal window to continue running commands.

Then, to deploy this canister to the playground, run the command:

dfx deploy hello_world_backend --playground

This command deploys just the backend canister, since that will be the canister you're focused on. To deploy all canisters listed in the dfx.json file, which by default includes a frontend canister in addition to the backend canister, you can use the dfx deploy --playground command without specifying the canister's name.

The output of this command will resemble the following:

WARN: The default identity is not stored securely. Do not use it to control a lot of cycles/ICP. Create a new identity with `dfx identity new` and use it in mainnet-facing commands with the `--identity` flag
Deployed canisters.
URLs:
  Backend canister via Candid interface:
    hello_world_backend: https://a4gq6-oaaaa-aaaab-qaa4q-cai.raw.icp0.io/?id=zeh3m-fiaaa-aaaab-qacda-cai

The identity warning returned in the output of this command is expected. At this point, we have not configured dfx to use an identity, so the default is used. The default identity's seed phrase is not stored securely, and therefore should not be used to control cycles or ICP tokens.

Interacting with the canister via the CLI​

Once deployed, the canister can be interacted with from the command line, or from the URL shown in the output above that refers to the backend canister's Candid interface. First, let's look at using the command line.

If you recall from the 0.6: Introduction to dfx module, our canister has a single method called greet, which you can call using a command such as:

dfx canister --playground call hello_world_backend greet '("everyone")'

This command sends a message to the hello_world_backend canister that has been deployed on the playground network (indicated by the --playground flag), and calls the method greet, then passes the text '("everyone")' to the method.

As a result, the canister should return the following reply:

("Hello, everyone!")

You can change the text portion to anything you'd like to test the method further. For example, instead of 'everyone', you can pass 'developers' into the method, such as:

dfx canister --playground call hello_world_backend greet '("developers")'

This will return the reply:

("Hello, developers!")

Any commands that intend to target a canister deployed to the playground must use the --playground or --network playground flag in order to target the borrowed canister(s).

Interacting with the canister via the Candid interface​

Now let's use the Candid interface instead. To use the Candid interface instead of the command line, first navigate to the URL provided in the output when the canister was deployed. This URL will look like:

http://bkyz2-fmaaa-aaaaa-qaaaq-cai.icp0.io

The user interface should resemble the following:

Candid UI 1

In this interface, you can see the single method in the canister, greet, and the possible parameters that can be passed, (text). In the text box provided, enter the text you'd like to pass to the greet method. Then, select the query button to submit the call.

Candid UI 2

You will see the output of the method in the output log on the right side of the interface, plus in the output below the method, as shown below.

Candid UI 3

You can play around with this user interface by inputting different text, such as 'developers' instead of 'everyone'.

Candid UI 4

Need help?​

Did you get stuck somewhere in this tutorial, or feel like you need additional help understanding some of the concepts? The ICP community has several resources available for developers, like working groups and bootcamps, along with our Discord community, forum, and events such as hackathons. Here are a few to check out:

Next steps​

Now that you've explored a live canister deployed on the playground, you'll move onto developing your own dapp rather than using the default template files. But first, let's go over the basics of Motoko in Motoko level 1.