Deployment

There are two main Internet Computer (IC) environments that you will generally interact with: the local replica and mainnet.

When developing on your local machine, our recommended flow is to start up a local replica in your project's root directoy and then deploy to it for local testing.

Starting the local replica

Open a terminal and navigate to your project's root directory:

dfx start

Alternatively you can start the local replica as a background process:

dfx start --background

If you want extra speedy deploys:

dfx start --artificial-delay 0

or

dfx start --background --artificial-delay 0

If you want to stop a local replica running in the background:

dfx stop

If you ever see this error after dfx stop:

Error: Failed to kill all processes.  Remaining: 627221 626923 627260

Then try this:

sudo kill -9 627221
sudo kill -9 626923
sudo kill -9 627260

If your replica starts behaving strangely, we recommend starting the replica clean, which will clean the dfx state of your project:

dfx start --clean

Deploying to the local replica

To deploy all canisters defined in your dfx.json:

dfx deploy

To deploy an individual canister:

dfx deploy canister_name

If you have problems deploying see Common deployment issues.

Interacting with your canister

As a developer you can generally interact with your canister in three ways:

dfx command line

You can see a more complete reference here.

The commands you are likely to use most frequently are:

# assume a canister named my_canister

# builds and deploys all canisters specified in dfx.json
dfx deploy

# builds all canisters specified in dfx.json
dfx build

# builds and deploys my_canister
dfx deploy my_canister

# builds my_canister
dfx build my_canister

# removes the Wasm binary and state of my_canister
dfx uninstall-code my_canister

# calls the method_name method on my_canister with a string argument
dfx canister call my_canister method_name '("This is a Candid string argument")'

dfx web UI

After deploying your canister, you should see output similar to the following in your terminal:

Deployed canisters.
URLs:
  Backend canister via Candid interface:
    my_canister: http://127.0.0.1:8000/?canisterId=ryjl3-tyaaa-aaaaa-aaaba-cai&id=rrkah-fqaaa-aaaaa-aaaaq-cai

Open up http://127.0.0.1:8000/?canisterId=ryjl3-tyaaa-aaaaa-aaaba-cai&id=rrkah-fqaaa-aaaaa-aaaaq-cai to access the web UI.

@dfinity/agent

@dfinity/agent is the TypeScript/JavaScript client library for interacting with canisters on the IC. If you are building a client web application, this is probably what you'll want to use.

There are other agents for other languages as well:

Deploying to mainnet

Assuming you are setup with cycles, then you are ready to deploy to mainnet.

To deploy all canisters defined in your dfx.json:

dfx deploy --network ic

To deploy an individual canister:

dfx deploy --network ic canister_name

If you have problems deploying see Common deployment issues.

Common deployment issues

If you run into an error during deployment, try the following:

  1. Ensure that you have followed the instructions correctly in the installation chapter, especially noting the common installation issues

  2. Ensure that you have created and activated your virtual environment, and that you have done the following from within that virtual environment: installed Kybra, installed the Kybra dfx extension, and run dfx deploy:

    ~/.pyenv/versions/3.10.7/bin/python -m venv venv
source venv/bin/activate
pip install kybra
python -m kybra install-dfx-extension
dfx deploy

  3. Look for more error output by adding the KYBRA_VERBOSE=true environment variable to dfx deploy like so: KYBRA_VERBOSE=true dfx deploy

  4. Look for errors in each of the files in ~/.config/kybra/[kybra_version]/logs

  5. If the problem is still not resolved, reach out with any error outputs in the Discord channel