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.18

  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.11.1"  "impl_version": "2020-10-14"
}

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"...
"hello" canister created on network "ic" with canister id: "2lolz-fluaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q"
Creating canister "hello_assets"...
"hello_assets" canister created on network "ic" with canister id: "hupnp-k3uaa-aaaaa-aaaaa-caaaa-aaaaa-aaaaa-q"
Building canisters...
Building frontend...
Installing canisters...
Installing code for canister hello, with canister_id 2lolz-fluaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q
Installing code for canister hello_assets, with canister_id hupnp-k3uaa-aaaaa-aaaaa-caaaa-aaaaa-aaaaa-q
Deployed canisters.
    If you created a project with a different name, keep in mind that your canister names will match your project name instead of hello and hello_assets.

  4. Check that your wallet canister is properly configured and holds a balance of cycles by running a command similar to the following:

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

    The command returns the cycle balance for the wallet canister identifier you specified. For example:

    (99999994564407680)

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

    dfx canister call hello greet everyone

    This example uses the dfx canister call command to pass "everyone" as an argument to the greet function.

    Remember, however, that if you created a project with a different name, the canister name will match your project name and you’ll need to modify the command line to match the name you used instead of hello.

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

    For example:

    ("Hello, everyone!")

  7. Rerun the command to check the cycle balance for your wallet canister by running a command similar to the following:

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

    Note that a small number of cycles have been deducted from the cycle balance. For example:

    (99999994564312294)

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.

  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://hupnp-k3uaa-aaaaa-aaaaa-caaaa-aaaaa-aaaaa-q.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 the Tutorials section of the SDK Developer Tools and in the Motoko Programming Language Guide.