Skip to main content

Configure client and deploy your dapp to Testnet

This topic covers configuring your client and deploying and updating a dapp with the Chromia CLI to the public Testnet.

Configure client for Testnet​

You can use the postchain-client with a dapp backend running on the Chromia network by setting up a connection to the Directory chain. Every blockchain connects to the Directory chain, read more here. Through the Directory chain connection, the client finds all the addresses where your dapp is currently running and establishes a connection encountering the list of addresses.

info

If you're configuring your client for the public Chromia network, use the following Directory chain node URL as the chromiaD1Url and chromiaD1blockchainRID variable below:

const chromiaD1Url = "https://testnet2.chromia.dev:7740";

const chromiaD1blockchainRID = "8C5AB44B61934386D00A446D264810E19B3B8C0E28DF6CFF54966E7814BDCD11";

For the current network of Chromia, there is only one node using HTTPS (https://testnet2.chromia.dev:7740). Therefore, if you are hosting your front end using HTTPS, you must configure your client to only connect to that single node. Skip the following section and use the previous example, substituting the above node URL.

To make this possible, you need a dapp. For more information, see Deploy your dapp to Testnet.

  1. Remove the local key pair in the client code (configured for a local setup). Instead, link to your key pair stored somewhere secure. For more information, see Deploy your dapp to Testnet.
//Key pair
const adminPubkey = Buffer.from("<PubkeyLink>", "hex");
const adminPrivkey = Buffer.from("<PrivkeyLink>", "hex");

To connect to the Chromia network, specify a URL and a Blockchain RID of a Chromia node running the Directory chain in the client code file.

The REST Client is then configured for the specific Chromia base URL and Blockchain RID. It's followed by an instance of a Chromia Client provider. It uses the REST Client instance and allows calls to the Directory chain.

After that, you can set a connection with a blockchain of the dapp Blockchain RID. It returns a REST Client with the addresses of the nodes that run your blockchain.

  1. In the client code file (configured for a local setup), replace the following part
const nodeApiUrl = "http://localhost:7740/"; //Using default postchain node REST API port
const blockchainRID = "<BlockchainRID>"; //Dapp Blockchain RID
const rest = pcl.restClient.createRestClient([nodeApiUrl], blockchainRID); //REST Client connection

with this part.

//Connection input
const chromiaD1blockchainRID = "<BlockchainRID>"; //Target Blockchain RID
const chromiaD1Url = "<TargetUrl>"; //Target URL

//Connection setup
const restD1 = pcl.restClient.createRestClient(
  [chromiaD1Url],
  chromiaD1blockchainRID,
  5,
  1000
); //REST Client connection
const chromiaClient = pcl.chromiaClient.chromiaClientProvider(
  chromiaD1blockchainRID,
  restD1
); //Chromia Client provider
const dappBlockchainRID = "<BlockchainRID>"; //Dapp Blockchain RID
const rest = await chromiaClient.blockchainConnection(dappBlockchainRID); //Blockchain connection

  1. Replace <TargetUrl> for chromiaD1URL and <BlockchainRID> for chromiaD1blockchainRID with the URL and the Blockchain RID of a Chromia node running the Directory chain. Also, replace <BlockchainRID> for dappBlockchainRID with your dapp Blockchain RID.

  2. You can now use the blockchain connection to initialize a gtx client

const gtx = pcl.gtxClient.createClient(rest, blockchainRID, ["set_name"]); //gtx Client connection

With these steps, you are ready to use the postchain-client with a dapp backend running on the Chromia network.

Deploy your dapp to Testnet​

Now, you can deploy and update your dapp with the Chromia CLI to the public Testnet. For more information, see deployment command.

Prerequisite​

Deploy the dapp​

The important 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. Write the following command to create a .secret file with a generated key pair (privkey and pubkey).
chr keygen --save .secret

You find the public and private key 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
privkey=<privkey>
pubkey=<pubkey>

Once you have your key pair, you need to stake Chroma token to deploy a dapp to the current testnet.

  1. To stake Chroma token, follow the instructions on the Staking Page. Once you stake a minimum of 100 CHR, you can request a container ID. You need to use this container ID to deploy your dapp in the following example.
info

The current public testnet has limited capacity; therefore, it requires staking. This might change as we increase the capacity of the testnet.

Once you receive the container ID, the container gets deleted from the network unless you deploy a dapp within 48 hours. If that happens, you can return to the staking page and request a new container ID if there is still capacity.

Note that this is a testnet; data may not persist between testnet updates.

  1. Copy the deployments key in the config.yml file example below into your config file. Replace the <ContainerID> with the Container ID you got from the staking page.
blockchains:
  hello: #Name of the blockchain
    module: main #Entrypoint to the project
deployments:
  testnet: #Deployment Target name
    brid: x"8C5AB44B61934386D00A446D264810E19B3B8C0E28DF6CFF54966E7814BDCD11" #Blockchain RID for the testnet management chain
    url: https://testnet2.chromia.dev:7740 #Target URL for one of the nodes in the testnet
    container: <ContainerID> #Container ID
  1. Write the following command to deploy a specific chain to a specific target.
chr deployment create --settings config.yml --network testnet --blockchain hello --secret .secret
info

If you get an error while deploying your dapp then make some changes to 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 could look as follows.

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

Great. You have now done your first deployment. Please see the section Configure Client for Chromia Network 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.

info

The limitations on updating Rell entities are available here.

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

blockchains:
  hello:
    module: main
deployments:
  testnet:
    brid: x"8C5AB44B61934386D00A446D264810E19B3B8C0E28DF6CFF54966E7814BDCD11"
    url: https://testnet2.chromia.dev:7740
    container: <ContainerID>
    chains:
      hello: x"<BlockchainRID>" #Dapp Blockchain RID
  1. Write the following command to update your dapp:
chr deployment update --settings config.yml --network testnet --blockchain hello --secret .secret

When updating a dapp, you use the same command as for deployment but with the dapp Blockchain RID included in the config.yml file. You aren't prompted with anything this time, but a snapshot file gets created, which is also the case for deployment.