Skip to main content

Deploy your dapp to testnet

This topic covers deploying and updating a dapp with the Chromia CLI to the public testnet. See deployment command for more information.


Deploy the dapp

The essential files for the deployment of a dapp are as follows:

Begin with generating a public and private key pair that's available in a .secret file.

  1. Run the following command to create a .secret file with a generated key pair (privkey and pubkey).

    chr keygen --file .secret

    You find the public and private keys in the created .secret file. You can copy and share the public key, while the private key should be kept as a secret in the .secret file.

    # .secret
    # Keypair generated using...
    # Date
  2. Once you have your key pair, you need to lease a container on the testnet using test Chroma token (tCHR). You can get tCHR through a faucet by following the instructions on the Staking Page. As a spam prevention measure, you must stake a small amount of real CHR (10 CHR), which will enable you to ask for new test tokens weekly from the faucet. To learn more about Chromia's container lease model, visit the hosting fee overview topic.


    If you are participating in the Incentivized Testing Program, you can deploy to several testnets. Select the appropriate network when going through the flow on the Staking page:

    • ProjectNet: Select this network to deploy a dapp for learning, testing, and demo purposes.

    • HackNet: Select this network if you are participating in the bug bounty and deploying a dapp as part of your search for bugs and security vulnerabilities.

    Note that these are testnets; data may not persist between testnet updates.

    To lease a container, follow the instructions on the Staking page, selecting the appropriate network. Once you stake, get tCHR, and lease a container, you'll receive a container ID. You need to use this container ID to deploy your dapp in the following example.

  3. Copy the deployments key in the chromia.yml file example below into your config file. Replace the <ContainerID> with the Container ID you got from the staking page.

    hello: # Name of the blockchain
    module: main # Entrypoint to the project
    testnet: # Deployment Target name
    brid: x"69035D70A99A6BFAF887E415352B40589F1AD1F8D2ADF848FE995B23A8EC2127" # Blockchain RID for the testnet management chain
    url: # Target URL for one of the nodes in the testnet
    container: <ContainerID> # Container ID (Example - container: 15ddfcb25dcb43577ab311fe78aedab14fda25757c72a787420454728fb80304)

    The above example assumes you are deploying to ProjectNet. If you are deploying to HackNet, replace brid and url with the following values:

        brid: x"B06D83B5D2C7271B4E5906EED054BCD13F21CF3292E99E6C3158F1C544EB9882"
  4. Write the following command to deploy a specific chain to a specific target.

    chr deployment create --settings chromia.yml --network testnet --blockchain hello --secret .secret

    If you get an error while deploying your dapp, change your dapp code. Chromia uses dapp configuration and code to create the Blockchain RID, which must be unique for each dapp.

    After a successful deployment, you get the dapp Blockchain RID as a prompt in the terminal. It identifies your dapp for future deployments (updates). The prompt might look as follows:

    Add the following to your project settings file
    hello: x"<BlockchainRID>" #Dapp Blockchain RID
  5. Add the chains key with the <dapp name>: Blockchain RID from the prompt to the chromia.yml file. This is important for updating your dapp in the future.

Great. You have now done your first deployment. Please see the Configure client topic if you want to configure the client code to connect to your deployed dapp.

Update the dapp

Once you have done your first deployment, you can perform an update of your dapp.


The limitations on updating Rell entities are available here.

Your chromia.yml must now have the chains config included.

module: main
brid: <DirectoryBlockchainRID> # Blockchain RID for the testnet management chain
url: <SystemNodeURL> # Target URL for one of the system nodes in the testnet
container: <ContainerID> # ID obtained when leasing a container on the Staking Page
hello: x"<BlockchainRID>" # Dapp Blockchain RID

Run the following command to update your dapp:

chr deployment update --settings chromia.yml --network testnet --blockchain hello --secret .secret

To learn more about developing production-ready dapps, visit the Chromia course page.