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!