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.
- 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.
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:
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
First create a directory
my-codius-create-react-app, then create a
codius.json file in that directory with the following contents:
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
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.
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
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
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
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:
will be uploaded to host(s):
⚠ 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
expirationDate: "07-06-2018 11:41:40 -0700",
expires: "in 3 minutes",
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
✔ 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
on the following host(s):
with the current status:
expirationDate: "07-06-2018 11:46:35 -0700",
expires/expired: "in a minute",
totalPricePaid: "1524 µ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!