Quick start

This DFINITY Canister Software Development Kit (SDK) is an Alpha release that provides tools, sample code, and documentation to help you create programs to run on a locally-deployed Internet Computer client node.

For this Alpha release, only macOS and Linux platforms are supported. In addition, 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 that run on the Internet Computer platform, it only takes a few minutes to get up and running.

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 Software Development Kit (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)"

    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.

  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.

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

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. Create a new project directory for your first application by running the following commands:

    dfx new hello

    The dfx new hello command creates a new hello project with a default project directory, some template files, 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.

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

    cd hello

Build the program

Your new hello project includes a simple default program in the src/hello directory that you can compile.

To build the program executable:

  1. View the contents of the source directory for your project directory by running the following command:

    ls -l src/hello

    Note that the src/hello directory includes a default main.mo program for your project and a public directory. For this Quick start, you only need to use the main.mo program.

  2. Build the executable from the default main.mo file by running the following command:

    dfx build
  3. Verify 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 canister hello
    Building frontend
    Bundling frontend assets in the canister

Start the local network and deploy

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

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

    dfx start --background

    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.

    The --background option starts Internet Computer client processes then runs them in the background so that you can continue to the next step without opening another terminal shell on your local computer.

  2. Deploy the default program on the local network by running the following command:

    dfx canister install hello

    You should see an installation confirmation message for your canister similar to the following:

    Installing code for canister hello, with canister_id ic:795EA5F537665EED24
    Mar 04 15:35:16.710 INFO Successfully inserted an
    ingress message into IngressPool, Application:
    ArtifactPool
    Mar 04 15:35:17.968 INFO Created checkpoint @168961
    in 76.82103ms, StateManager: 1
  3. Call the predefined greet method in the program by running the following command:

    dfx canister call hello 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.

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

    For example:

    Mar 04 15:43:51.826 INFO Successfully inserted an
    ingress message into IngressPool, Application:
    ArtifactPool
    Mar 04 15:43:52.779 INFO Created checkpoint @169984
    in 68.44148ms, StateManager: 1
    ("Hello, there!")
  5. Stop the Internet Computer client processes running on your local computer by running the following command:

    dfx stop

Next steps

This Quick start touched on only a few key steps to introduce the basic workflow you follow to develop programs of your own. There are more detailed examples and tutorials for you to explore in the Developer’s Guide and in the Motoko Programming Language Guide.