Getting started

The DFINITY Canister Software Development Kit (SDK) provides tools, sample code, and documentation to help you create programs to run on a locally-deployed Internet Computer replica node. (You won’t be able to install your programs on an externally-managed Developer Network just yet, but that capability is coming soon.)

By developing programs that run on the Internet Computer platform, you can deploy secure, tamper-proof applications and provide web-based services without the restrictions or expense of a proprietary infrastructure, the complexities of database management and maintenance, or the investment in hardware required to run enterprise-scale software.

If you want to learn more about the Internet Computer platform and how it can transform distributed computing and the application landscape, check out Frequently Asked Questions or the videos posted on the DFINITY Official Youtube Channel.

If you are ready to start developing applications to run on the Internet Computer platform, it only takes a few minutes to get up and running.

As a preview of the steps, the following diagram illustrates the basic work flow.

Development work flow

Before you begin

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

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

  • You should have node.js installed if you want to include the default template files for front-end development in your project.

Download and install

The most straightforward option for accessing the DFINITY Canister SDK is to download the SDK package from within a terminal shell on your local computer. With this installation option, you can be logged on as any user and no additional software is required.

To download and install from a terminal shell:

  1. Open a terminal shell on your local computer.

    For example, on macOS open the Applications folder, then open Utilities and double-click Terminal.

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

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

    By default, this command installs the latest version of the DFINITY Canister SDK. You can, however, install a specific version, if needed. For example, if you want to test against a previous version, you can modify the command to include a version by running a command similar to the following:

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

    This command prompts you to read and accept the license agreement before installing the dfx command-line interface executable and its dependencies on your local computer.

    info: Executing DFINITY SDK install script, commit: 9bced56-2019-11-01T10:51:38-07:00
    
     DFINITY SDK
     Please READ the following license:
    
    DFINITY Foundation -- All rights reserved. This is an ALPHA version of the DFINITY Canister Software Development Kit (SDK).
    Permission is hereby granted to use AS IS and only subject to the Alpha DFINITY Canister SDK License Agreement which can be found here [https://sdk.dfinity.org/sdk-license-agreement].
    It comes with NO WARRANTY.
  3. Review the license agreement, then type y and press Enter if you want to continue with the installation.

    Do you agree and wish to install the DFINITY ALPHA SDK [y/N]?

    The default response is No. You must type y and press Enter to continue.

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

    info: Version found: 0.5.4
    info: Creating uninstall script in ~/.cache/dfinity
    info: uninstall path=/Users/pubs/.cache/dfinity/uninstall.sh
    info: Checking for latest release...
    Will install in: /usr/local/bin
    info: Installed /usr/local/bin/dfx

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 SDK developer command-line interface installed and the executable is available in your PATH by running the following command:

    dfx --version

    The command displays version information for the developer command-line interface similar to the following:

    dfx 0.5.4
  3. Preview usage information for the other developer command-line interface subcommands by running the following command:

    dfx --help

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

Create a new project

You are now ready to create a new project for your first sample application.

To create a new project directory for your first application:

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

  2. Create a folder for your Internet Computer sample projects by running the following command in your home directory or current working folder:

    mkdir ~/ic-projects
  3. Change to your sample projects folder. For example:

    cd ~/ic-projects
  4. Create a new project directory for your first application by running the following command:

    dfx new hello_world

    The dfx new hello_world command creates a new hello_world project, including a default project directory structure under the new project name and a new Git repository for your project. If you have node.js installed locally, creating a new project also adds some template front-end code and dependencies.

    To ensure that project names are valid when used in JavaScript, Motoko, and other contexts, you should only use alphanumeric characters and underscores. You cannot include dashes or any special characters.

    The command displays output similar to the following excerpt:

    Fetching manifest https://sdk.dfinity.org/manifest.json
    Creating new project "hello_world"...
    CREATE       hello_world/src/hello_world/main.mo (107B)...
    CREATE       hello_world/dfx.json (320B)...
    CREATE       hello_world/.gitignore (189B)...
    CREATE       hello_world/README.md (1.01KB)...
    CREATE       hello_world/src/hello_world/public/index.js (155B)...
    CREATE       hello_world/package.json (263B)...
    CREATE       hello_world/webpack.config.js (1.76KB)...
  5. View the default directory structure by running the following command:

    ls -l hello_world

    By default, the project directory structure includes at least one source subdirectory, a template README.md file, and a default dfx.json configuration file.

    Depending on whether you have node.js installed, your project directory might include some or all of the following files:

    hello_world/
    ├── README.md      # default project documentation
    ├── dfx.json       # project configuration file
    ├── node_modules   # libraries for front-end development
    ├── package-lock.json
    ├── package.json
    ├── src            # source files directory
    |   └── hello_world
    │       ├── main.mo
    │       └── public
    │           └── index.js
    └── webpack.config.js

    At a minimum, the default project directory includes the following folders and files:

    • A default README file for documenting your project in the repository.

    • A default dfx.json configuration file to set configurable options for your project.

    • A default src directory for all of the source files required by your application.

      The default src directory includes a template main.mo file that you can modify or replace to include your core programming logic.

      Because this tutorial focuses on the basics of getting started, you are only going to use the main.mo file. If you have node.js installed, your project directory includes additional files and directories that you can use to define the front-end interface for your application. The front-end development and template files in the public folder are discussed a little later.

Reviewing template files for your first program

By default, creating a new project adds some template files to your project directory. You can edit these template files to include your own code to speed up the development cycle. To try it out, you can use the default template files to create a simple program that prints a text string using Motoko code.

To review the template files for your program:

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

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

    cd hello_world
  3. Open the dfx.json configuration file in a text editor to review the default settings.

    For example:

    {
      "canisters": {
        "hello_world": {
          "frontend": {
            "entrypoint": "src/hello_world/public/index.js"
          },
          "main": "src/hello_world/main.mo"
        }
      },
      "defaults": {
        "build": {
          "output": "canisters/"
        },
        "start": {
          "address": "127.0.0.1",
          "port": 8000,
          "serve_root": "canisters/hello_world/assets"
        }
      },
      "dfx": "0.5.4",
      "version": 1
    }

    You can leave the default settings as they are. The default settings enable you to build and deploy your hello_world project from the default main.mo source code as a WebAssembly module named hello_world.

  4. Close the dfx.json file to continue.

  5. Change to the src/hello_world directory.

    cd src/hello_world
  6. Open the main.mo file in a text editor and review the code in the template script:

    actor {
        public func greet(name : Text) : async Text {
            return "Hello, " # name # "!";
        };
    };

    You might notice that this sample code does not define a main function, which some programming languages require. For Motoko, the main function is implicit in the file itself. The implicit main function is a common convention in some scripting languages, such as Python and Perl.

    Although the traditional first program "Hello, World!" example normally illustrates how you can print a string using a print or println function, that traditional program would not represent a typical use case for Motoko programs that run on the Internet Computer.

    We’ll explore code that uses actor objects and asynchronous message handling more a little later. For now, you can continue to the next section to build the simple program from the default main.mo file.

  7. Close the main.mo file to continue.

Build the program

You are now ready to compile the default program into an executable WebAssembly module.

To build the program executable:

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

  2. Navigate to the root of your hello_world project folder.

    For example:

    cd ~/ic-projects/hello_world

    Note that this step is required because you must run the dfx build command from within the project directory structure.

  3. Build the executable canister by running the following command:

    dfx build

    The command displays output indicating that the build is successful.

    For example, if you have node.js installed you should see output similar to the following:

    Building canisters hello_world
    Building frontend
    Bundling frontend assets in the canister
  4. Verify that the canisters/hello_world directory created by the build command contains the WebAssembly and related application files by running the following command.

    ls -l canisters/hello_world/

    For example, the command returns output similar to the following if you have node.js installed locally:

    total 144
    -rw-r--r--  1 pubs  staff      8 Jan 28 13:30 _canister.id
    drwxr-xr-x  4 pubs  staff    128 Jan 28 13:30 assets
    -rw-r--r--  1 pubs  staff     43 Jan 28 13:30 main.did
    -rw-r--r--  1 pubs  staff    117 Jan 28 13:30 main.did.js
    -rw-r--r--  1 pubs  staff    155 Jan 28 13:30 main.js
    -rw-r--r--  1 pubs  staff  53420 Jan 28 13:30 main.wasm

    The canisters/hello_world directory contains the following key files:

    • The _canister.id file contains a randomly-generated identifier for your compiled program.

    • The main.did file contains an interface description for your program.

    • The main.js file contains a JavaScript representation of the canister interface for your program.

    • The main.wasm file contains the compiled WebAssembly for your program.

The canisters/hello_world directory also contains an assets subdirectory for your front-end JavaScript, custom CSS, and HTML files. In addition to these files, the dfx build command creates an +idl_ directory with an interface description file labeled with your canister identifier (for example, with a file name with the randomly-generated identifier similar to 81DDA04F69F40FEEAC.did).

Start the local network and deploy

You now have a program that can be deployed on your local replica network.

To deploy the program on your local network:

  1. Open a terminal shell on your local computer, if you don’t already have one open, and navigate to your hello_world project directory.

  2. Start the Internet Computer network on your local computer by running the following command:

    dfx start

    Depending on your platform and local security settings, you might see a warning displayed. If you are prompted to allow or deny incoming network connections, click Allow.

    You can use the --background option to start the Internet Computer replica processes then run them in the background. If you use the --background option, you can continue to the next step without opening another terminal shell on your local computer.

    If you don’t specify the --background option, you must open a new terminal shell. For example, if you are in the Terminal application on macOS, click Shell, then click New Window. You can then navigate to your hello_world project directory in the new terminal shell before continuing to the next step.

    After you start the local network, you should see the Internet Computer replica started message and details about your current network configuration.

  3. Deploy your hello_world project on the local network by running the dfx canister install command and specifying a canister_name that matches the canister name specified in the dfx.json configuration file.

    For this tutorial, the canister name is hello_world and the path to the compiled code for the canister you want to deploy is canisters/hello_world/main.wasm, so you can deploy the canister by running the following command:

    dfx canister install hello_world

    The command output displays output similar to the following:

    Installing code for canister hello_world, with canister_id ic:81DDA04F69F40FEEAC
  4. Call the predefined greet method in the program by running the following command:

    dfx canister call hello_world greet "there" --type string

    This example uses the dfx canister call command to pass "there" as an argument of type string to the greet function.

  5. Verify the command displays the return value of the greet function (Hello, there!).

    For example:

    ("Hello, there!")
  6. Stop the Internet Computer replica processes running on your local computer by running the following command:

    dfx stop

View the default front-end

If you have node.js installed in your development environment, your project includes a simple front-end example that uses a template index.js JavaScript file and a sample index.html file for accessing the hello_world program in a browser.

To explore the default front-end template:

  1. Open a terminal shell on your local computer, if you don’t already have one open, and navigate to your hello_world project directory.

  2. Open the src/hello_world/public/index.js file in a text editor and review the code in the template script:

    import hello_world from 'ic:canisters/hello_world';
    
    hello_world.greet(window.prompt("Enter your name:")).then(greeting => {
      window.alert(greeting);
    });

    The template index.js file uses the Document Object Model (DOM) to describe the structure and content of a document on the web.

    This sample file imports the canister you created and calls the greet function in a prompt window.

  3. Close the index.js file to continue.

  4. View the static assets created in the canisters directory by running following command:

    ls -l canisters/hello_world/assets/

    The command displays output similar to the following if you have node.js installed.

    total 24
    -rw-r--r--  1 pubs  staff  1191 Jan 28 13:30 index.js
    -rw-r--r--  1 pubs  staff  5524 Jan 28 13:30 index.js.map

    These files were generated automatically by the dfx build command using node modules and the template index.js file.

  5. Start the Internet Computer network on your local computer by running the following command:

    dfx start
  6. Open a browser and navigate to the address and port number specified in the dfx.json configuration file.

    By default, the URL uses the localhost address (127.0.0.1) and port number 8000, so you can navigate to the front-end for the hello_world program using 127.0.0.1:8000 for the URL. In addition to the host and port, the URL you specify needs to include canisterId parameter to identify the canister that you want the web server to display. To specify the canister, append the identifier using the following syntax:

?canisterId=ic:_canister_identifier_

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

+

http://localhost:8000/?canisterId=ic:81DDA04F69F40FEEAC
  1. Verify that you are prompted to type a greeting.

    For example:

    Hello world prompt window

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

    For example:

    Hello world return string

Updating the SDK

If a new version of the SDK is available for download after your initial installation, you should install the updated version at your earliest convenience to get the latest fixes and enhancements as soon as possible. You can use the dfx upgrade command to compare the version you have currently installed against the latest version available for download. If a newer version of dfx is available, the dfx upgrade command automatically downloads and installs the latest version.

Note that you don’t need to uninstall the software before installing the new version. However, if you want to perform a clean installation rather than an upgrade, you can first uninstall the software as described in Uninstalling the SDK, then re-run the download and installation command.

For information about the features and fixes in the latest release, see the Release notes.

Uninstalling the SDK

When you install the SDK, the installation script puts the required binary files in a local directory and creates a cache. You can remove the SDK binaries and cache from your local computer by running the uninstall script located in the .cache folder.

For example:

~/.cache/dfinity/uninstall.sh

If you are uninstalling because you want to immediately reinstall a clean version of dfx, you can run the following command:

~/.cache/dfinity/uninstall.sh && sh -ci "$(curl -sSL https://sdk.dfinity.org/install.sh)"