Network deployment

This Quick Start scenario assumes that you are installing the DFINITY Canister SDK for the first time and deploying the default project on the Internet Computer network running remotely.

If you are only deploying projects in a local development environment, see the Local development scenario.

To get started, let’s build and deploy a simple Hello application that has just one function—called greet. The greet function accepts one text argument and returns the result with a greeting similar to Hello, everyone! in a terminal if you run the application using the command-line or in an alert pop-up window if you access the application in a browser.

Before you begin

Before you download and install this release of the DFINITY Canister SDK, verify the following:

  • You have an internet connection and access to a shell terminal on your local macOS or Linux computer.

    Currently, the DFINITY Canister SDK only runs on computers with a macOS or Linux operating system.

  • You have node.js installed if you want to access the default front-end for the default project.

If you aren’t sure how to open a new terminal shell on your local computer or how to install node.js, see Preliminary steps for newcomers. If you are comfortable meeting the prerequisites without instructions, continue to Download and install.

Download and install

You can download the latest version of the DFINITY Canister Software Development Kit (SDK) directly from within a terminal shell on your local computer.

To download and install:

  1. Open a terminal shell on your local computer.

    For example, open Applications, Utilities, then double-click Terminal or press ⌘+spacebar to open Search, then type terminal.

  2. Download and install the DFINITY Canister SDK package by running the following command:

    sh -ci "$(curl -fsSL https://sdk.dfinity.org/install.sh)"

    This command prompts you to read and accept the license agreement before installing the DFINITY execution command-line interface (CLI) and its dependencies on your local computer.

  3. Type y and press Return to continue with the installation.

    The command displays information about the components being installed on the local computer.

Verify the SDK is ready to use

If the installation script runs without any errors, everything you need to start developing programs that run on the Internet Computer platform will be available on your local computer.

To verify the SDK is ready to use:

  1. Open a terminal shell on your local computer, if you don’t already have one open.

  2. Check that you have the DFINITY execution command-line interface (CLI) installed and the dfx executable is available in your PATH by running the following command:

    dfx --version

    The command displays version information for the dfx command-line executable similar to the following:

    dfx 0.6.26

  3. Preview usage information for the other dfx command-line sub-commands by running the following command:

    dfx --help

    The command displays usage information for the dfx parent command and its subcommands.

Create a new project

Applications for the Internet Computer start as projects. You create projects using the dfx parent command and its subcommands. Creating a new project with dfx adds a default project directory structure to your development workspace with template files to get you started.

To create a new project for your first application:

  1. Open a terminal shell on your local computer, if you don’t already have one open.

  2. Create a new project named hello by running the following command:

    dfx new hello

    The dfx new hello command creates a new hello project directory, template files, and a new hello Git repository for your project.

    If you use a different project name instead of hello, make note of the name you used. You’ll need to use that project name in place of the hello project name throughout these instructions.

  3. Change to your project directory by running the following command:

    cd hello

Check the connection to the network

Before you can deploy your first project on the Internet Computer network, you need to connect to the network gateway running remotely on a sub-network that you can access. A network alias for the Internet Computer network gateway is configured in your project dfx.json file by default.

To check your connection to the Internet Computer network:

  1. Check that you are in the root directory for your project, if needed.

  2. Check the current status of the Internet Computer network and your ability to connect to it by running the following command for the network alias ic:

    dfx ping ic

    If you modify the network alias for the Internet Computer network in your dfx.json file, replace the ic network alias with the alias you are using in this and subsequent commands.

  3. Verify the command returns information about the Internet Computer network to which you are connecting.

    For example, you should see output similar to the following:

    {
  "ic_api_version": "0.14.0"  "impl_hash": "40d5e890ae5c3558fbb4281ec04a5c0d0c1c0104012a33dfc8ecb0445057f405"  "impl_version": "0.1.0"  "root_key": [48, 129, 130, 48, 29, 6, 13, 43, 6, 1, 4, 1, 130, 220, 124, 5, 3, 1, 2, 1, 6, 12, 43, 6, 1, 4, 1, 130, 220, 124, 5, 3, 2, 1, 3, 97, 0, 133, 168, 228, 168, 232, 127, 43, 51, 212, 173, 127, 167, 169, 84, 223, 125, 69, 157, 31, 105, 91, 34, 207, 123, 136, 227, 152, 187, 36, 246, 25, 58, 90, 24, 169, 86, 122, 201, 212, 11, 111, 43, 156, 193, 106, 11, 210, 217, 22, 13, 187, 148, 153, 152, 176, 171, 45, 130, 247, 231, 157, 251, 92, 190, 202, 13, 150, 116, 95, 187, 28, 157, 173, 170, 60, 156, 45, 127, 248, 25, 95, 9, 43, 102, 161, 46, 198, 237, 227, 77, 244, 79, 227, 134, 69, 161]
}

Register, build, and deploy the application

After you connect to the Internet Computer network, you can register, build, and deploy your application.

To deploy your first application on the Internet Computer:

  1. Check that you are still in the root directory for your project, if needed.

  2. Ensure that node modules are available in your project directory, if needed, by running the following command:

    npm install

    For more information about this step, see Ensuring node is available in a project.

  3. Register, build, and deploy your first application by running the following command:

    dfx deploy --network=ic

    The dfx deploy command output displays information about the operations it performs.

    For example, this step registers two network-specific identifiers—one for the hello main program and one for the hello_assets front-end user interface—and installation information similar to the following:

    Deploying all canisters.
Creating canisters...
Creating canister "hello"...
Creating the canister using the wallet canister...
Creating a wallet canister on the ic network.
The wallet canister on the "ic" network for user "default" is "oi7fh-tiaaa-aaaab-aahpq-cai"
"hello" canister created on network "ic" with canister id: "lue7c-yaaaa-aaaab-aahqa-cai"
Creating canister "hello_assets"...
Creating the canister using the wallet canister...
"hello_assets" canister created on network "ic" with canister id: "ltfzw-vyaaa-aaaab-aahqq-cai"
Building canisters...
Building frontend...
Installing canisters...
Installing code for canister hello, with canister_id lue7c-yaaaa-aaaab-aahqa-cai
Installing code for canister hello_assets, with canister_id ltfzw-vyaaa-aaaab-aahqq-cai
Authorizing our identity (default) to the asset canister...
Uploading assets to asset canister...
Deployed canisters.

  4. Call the hello canister and the predefined greet function by running the following command:

    dfx canister --network=ic call hello greet everyone

    Let’s take a closer look at this example:

    • Using the --network=ic option indicates that the canister you want to call is deployed on the ic network. The ic network alias is an internally-reserved alias for accessing the Internet Computer.

    • Note that the --network=ic option must precede the operation subcommand, which, in this case, is the dfx canister call command.

    • The hello argument specifies the name of the canister you want to call.

    • The greet argument specifies the name of the function you want to call in the hello canister.

    • The text string everyone is the argument that you want to pass to the greet function.

  5. Verify the command displays the return value of the greet function.

    For example:

    ("Hello, everyone!")

    You might have noticed that deploying your project automatically generated a wallet for your default identity. This wallet canister is preconfigured with cycles and provides a few basic functions that enable you to experiment with sending and receiving cycles without requiring an account with ICP tokens.

    If you didn’t notice the wallet canister identifier when you ran dfx deploy, you can look it up now by running the following command:

    dfx identity --network=ic get-wallet

  6. Check the cycle balance for your default wallet canister by running a command similar to the following:

    dfx canister --network=ic call <WALLET-CANISTER-ID> wallet_balance

    This command returns the balance for the wallet canister identifier you specified using the Candid syntax for record data types. For example, the command might display a record with an amount field (represented by the hash 3_573_748_184) and a balance of 99,999.974,174,602 cycles like this:

    (record { 3_573_748_184 = 99_999_974_174_602 })

  7. Call the greet function again with a different argument.

    For example:

    dfx canister --network=ic call hello greet '("San Francisco")'

  8. Rerun the command to check the cycle balance for your wallet.

    For example, you might run a command similar to the following if the wallet canister identifier is oi7fh-tiaaa-aaaab-aahpq-cai:

    dfx canister --network=ic call oi7fh-tiaaa-aaaab-aahpq-cai wallet_balance

    Note that in the new balance, a small number of cycles have been deducted from the previous total of cycles available. For example:

    (record { 3_573_748_184 = 99_999_974_082_913 })

    In this example, the new balance is 99,999,974,082,913 cycles.

Test the application front-end

Now that you have verified that your application has been deployed and tested its operation using the command line, let’s verify that you can access the front-end pop-up window using your web browser.

To access the application front-end:

  1. Open a browser.

  2. Navigate to the front-end for the application using a URL that consists of the hello_assets identifier and the .ic0.app suffix.

    For example, the full URL should look similar to the following:

    https://wmbea-daaaa-aaaab-aacjq-cai.ic0.app/

    Navigating to this URL displays the prompt pop-up window. For example:

    Prompt pop-up window

  3. Type a greeting, then click OK to return the greeting.

    For example:

    Hello

  4. Click OK to close the alert pop-up window.

Next steps

Now that you have seen how to deploy an application on the Internet Computer network, you are ready to develop and deploy programs of your own. There are more detailed examples and tutorials for you to explore in Tutorials, the examples repository, and in the Motoko Programming Language Guide.