Running a simple React app on the Codius smart contract platform

Note: This guide has been updated as of July 10 2018 for Codius CLI 3.0.0.

Codius is a distributed peer-peer hosting platform that allows for third-party verified smart contracts. This flexibility is enabled by the fact that Codius hosts manage ‘pods’, which are hardware-isolated virtual machines that run code uploaded by users. Users package their software inside of containers and multiple containers can run together inside of a pod. This code can be in any language, allowing complete flexibility. Moreover, users can pay for this with any currency through the Interledger Protocol (ILP).

This article will walk you through how we can upload a simple docker image of a React app onto a Codius host. The Codius CLI ReadMe contains a more detailed description of uploading contracts.

Prerequisites

• Install Node.js (version 8.9.4 or higher)
• An XRP Wallet: Codius runs a local instance of Moneyd in order to handle payments. Note that the wallet you use here cannot be used with any other instance of Moneyd. Install Node.js (version 8.9.4 or higher)
• Running Moneyd on the livenet. Follow this tutorial for more information.

Basic Configuration

Firstly we need to install the Codius CLI by running the following command to install it to your global npm packages.

npm install -g codius

It can then be run with the command codius. Please visit this link for more on how the Codius CLI works.

Then we need to create and configure our Codius Manifest folder with 2 files: codius.json and codiusvars.json . The codius.json file allows the user to specify container images to be run, public and private environment variable names, and even small files that are injected into the containers. The codiusvars.json file allows the user to set values for the public and private variables used in the codius.json file.

First create a directory my-codius-create-react-app, then create a codius.json file in that directory with the following contents:

{
  "manifest": {
    "name": "my-codius-create-react-app",
    "version": "1.0.0",
    "machine": "small",
    "port": "3000",
    "containers": [{
      "id": "app",
      "image": "androswong418/example-pod-1@sha256:8933bced1637e7d3b08c4aa50b96a45aef0b63f504f595bb890f57253af68b11"
    }]
  }
}

The port field specifies the port we want our pod to expose, and the containers field is an array which includes images to be run. In our case this is a Docker image of Facebook’s [create-react-app](https://github.com/facebook/create-react-app). However since both CMD and WORKDIR are specified in the Dockerfile for this image, we do not need to include them in the object within the array. For more information on the Codius manifest specification, follow this link.

We will also need to create an empty codiusvars.json file in the same directory which is used to support environment variables in the container when used. For our purposes here the file is empty but the Codius CLI requires that it be present.

{
  "vars": {
    "public": {},
    "private": {}
  }
}

Uploading our Pod

Now that the manifest file is specified, we can upload our code onto a Codius host using the CLI we installed previously. We will be uploading to my host https://codius.tinypolarbear.com. Since the CLI looks for the codius.json and codiusvars.json in the directory where it is run, first navigate into my-codius-create-react-app then run the command:

codius upload --host https://codius.tinypolarbear.com --duration 200

Since duration is measured in seconds, that means the pod will run on the host for 4 minutes. It is important to note here that the user does not need to specify a host. If the --host is included without specifying a URL, then the CLI will automatically discover a running host for the code to run.

The CLI will then run and use the codius.json & codiusvars files to generate the full Codius Manifest which it will output to the user. This Codius Manifest that is output is what used to create the Manifest Hash. You should see a message like:

Generated Manifest:
{
  manifest: {
    name: "my-codius-create-react-app",
    version: "1.0.0",
    machine: "small",
    port: "3000",
    containers: [
      {
        id: "app",
        image: "androswong418/example-pod-1@sha256:8933bced1637e7d3b08c4aa50b96a45aef0b63f504f595bb890f57253af68b11"
      }
    ]
  }
}
Manifest Hash:
lg6gjhhh2b3if2tzpbms6cr3hdmh7dixa2v4an6pz4tdxdmqtjpa
will be uploaded to host(s):
["https://codius.tinypolarbear.com"]
with options:
{
  maxMonthlyRate: 10,
  duration: 200,
  units: "XRP"
}
⚠ All information in the manifest property will be made public!
? Do you want to proceed with the pod upload? (y/N)

If everything looks good, type y which will proceed ahead with the upload. If the pod upload is successful, you should then get a message similar to this:

✔ Upload to https://codius.tinypolarbear.com Successful
{
  url: "https://lg6gjhhh2b3if2tzpbms6cr3hdmh7dixa2v4an6pz4tdxdmqtjpa.codius.tinypolarbear.com/",
  manifestHash: "lg6gjhhh2b3if2tzpbms6cr3hdmh7dixa2v4an6pz4tdxdmqtjpa",
  host: "https://codius.tinypolarbear.com",
  expiry: "2018-07-06T18:41:40.126Z",
  expirationDate: "07-06-2018 11:41:40 -0700",
  expires: "in 3 minutes",
  pricePaid: "762",
  units: "µXRP"
}
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
✔ 1 Successful Uploads
o Manifest Hash: lg6gjhhh2b3if2tzpbms6cr3hdmh7dixa2v4an6pz4tdxdmqtjpa
✔ Codius State File: default.codiusstate.json Updated

On successful upload a default.codiusstate.json file will be generated in your folder. This file is very important since it contains the generated manifest, the manifest hash, and the hosts that it was uploaded to. If you delete this file then you will lose the generated manifest from which the manifest hash is derived from. Do not delete this file unless you wish to make a new manifest.

NOTE: The manifest hash is derived from the generated manifest, this means that if you run upload again and use the —overwrite option it will generate a new manifest hash and overwrite your default.codiusstate.json resulting in the loss of your manifest hash and hosts where it is currently running. For this reason its recommended that you only use —overwrite if you no longer need to use the existing manifest hash. Best practice is to move your default.codiusstate.json to a folder or rename it so that you have a backup of your existing generated manifest and where it was uploaded.

I have set my Codius host’s DNS to point to a subdomain codius.tinypolarbear.com. As a result if you then visit https://lg6gjhhh2b3if2tzpbms6cr3hdmh7dixa2v4an6pz4tdxdmqtjpa.codius.tinypolarbear.com , our app should be there running!

To keep it running you can then run the codius extend command in the same folder. It will use the default.codiusstate.json to then extend the contract to the same hosts or it will upload it to the host again if the contract has expired. If we run codius extend you will see output similar to the following:

✔ Checking default.codiusstate.json exists
✔ Getting Codius State Details
Extending Manifest:
{
  manifest: {
    name: "my-codius-create-react-app",
    version: "1.0.0",
    machine: "small",
    port: "3000",
    containers: [
      {
        id: "app",
        image: "androswong418/example-pod-1@sha256:8933bced1637e7d3b08c4aa50b96a45aef0b63f504f595bb890f57253af68b11"
      }
    ]
  }
}
on the following host(s):
["https://codius.tinypolarbear.com"]
with the current status:
[
  {
    host: "https://codius.tinypolarbear.com",
    expirationDate: "07-06-2018 11:46:35 -0700",
    expires/expired: "in a minute",
    totalPricePaid: "1524 µXRP"
  }
]
with options:
{
  maxMonthlyRate: 10,
  duration: 200,
  units: "XRP"
}

This contains all the details about where the pod will be extended and what options will be used. By default it uses the same options as you used during the original upload. This allows you to keep a contract running without changing it. For more advanced features of the Codius CLI, please refer to this section.

As you can see, uploading code onto Codius is very simple. We will be running more advanced demos and tutorials, so make sure you subscribe on Medium and follow us on Twitter! Additionally, feel free to ask any questions you may have on our gitter!