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:
-
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
. -
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.
-
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:
-
Open a terminal shell on your local computer, if you don’t already have one open.
-
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
-
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:
-
Open a terminal shell on your local computer, if you don’t already have one open.
-
Create a new project named
hello
by running the following command:dfx new hello
The
dfx new hello
command creates a newhello
project directory, template files, and a newhello
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 thehello
project name throughout these instructions. -
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:
-
Check that you are in the root directory for your project, if needed.
-
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 theic
network alias with the alias you are using in this and subsequent commands. -
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:
-
Check that you are still in the root directory for your project, if needed.
-
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.
-
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 thehello
main program and one for thehello_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
andhello_assets
. -
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)
-
Call the
hello
canister and the predefinedgreet
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 thegreet
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
. -
Verify the command displays the return value of the
greet
function.For example:
("Hello, everyone!")
-
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.
-
Open a browser.
-
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:
-
Type a greeting, then click OK to return the greeting.
For example:
-
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.
-
Have questions? Contact us.
-
Want to join the community? Visit our community forum.
-
Want to stay informed about new features and updates? Sign up for Developer updates.