I wanted to create a guide about starting a Codius host from scratch. There's some amazing articles online, but some have ran into issues. I want to show you step-by-step how to get setup and what I did to get a live Codius host running... from scratch.
What Do We Need?
The following is a list of what we will need, before we can start.
- A Domain Name of your choice
- A Server (VPS or Bare Metal preferred) - I'm going to use Vultr for my VPS
- An XRP wallet funded with 30 XRP
- An XRP Secret Key. If you're not sure what it is: This is the post for you!
Part 1: First thing's first!
Getting a Domain This is simply a matter of getting a domain name of your choice from any domain seller. Once you have purchased the domain, you will need to use the Nameservers the hosting provider gave to you. However, as we're using Vultr in this tutorial, you'll need to use the following Nameservers:
ns1.vultr.com
ns2.vultr.com
We do this first, because DNS propergation can take some time, so it's a good idea to do this at the early stages of setting up. The domain will need to be propergated correctly before we can install an SSL (later).
Getting a Server
OK, the first step is to decide if you want to try and run a host locally (which I don't recommend) or if you would like to use a VPS or Bare Metal server. Without going into detail, I feel the VPS is a great way to build a very affordable Codius Host, and that's what I'll be going through in this guide. Go to Vultr.com and create an account.
After you've created an account and logged in, you'll be taken to the Dashboard page showing you all (if any) of your instances.
Note: An Instance in Vultr-talk is a server of some sort. eg. a VPS .
Click the button to Deploy New Server. You'll be taken to the 'Deploy New Instance' page.
Select the required location for the VPS, and select '64 bit OS' and 'CentOS 7 x64' as the Server type.
NOTE: We'll pause here for a moment before we continue with selecting the 'Server Size'. As stated in a post from Stefan on this page, each contract ran on a server will use 512MB memory, and you will also need some memory for the VPS itself.
For this reason, we recommend at least 2048MB (2GB) of memory on your VPS.
At this point in time, I wouldn't worry about any additional features, startup scripts, SSH keys and firewall groups. The domain I chose when I setup the server was: scserver.host (Smart Contract Server Hosting was the theory behind the name) So, I you can set your Hostname and Label to anything you wish, but your hostname should be something suitable. I decided on codius.scserver.host - Remember KISS: something I was told a long time ago... keep it simple stupid ;)
Once you've setup your Hostname and Label - hit the 'Deploy Now' button and you'll see something like this:
While it's installing... since we can see our assigned IP address, we can setup DNS for this VPS server. If you're following this guide and using Vultr, then you can get to your DNS panel by going to: https://my.vultr.com/dns/ - You may want to Bookmark this link for later ;) Enter your Domain name into the top box, and the IP address of your new VPS into the bottom box, and hit the 'Add' button:
You'll then be taken to the Manage DNS page for that domain, similar to the one I'm seeing:
Go back to https://my.vultr.com and hit the 'Manage' button next to your instance for your server. You'll be taken to the Server Information page for your Instance. You're going to need to SSH into your new server, and you're going to need your password in order to do so. To see your password, hit the little eye icon next to where it says password:
Your password will be displayed. Copy this down as you're going to need it for the next step.
Congratulations. So far, you've got a VPS server which meets the required specifications and you're ready to get stuck into the nitty-gritty part of setting up, configuring, installing and running an amazing Codius host!
Where we're at?
OK so currently, we've registered a domain name, updated the nameserves to use those provided by our hosting provider and we're waiting for the domain to propergate to our server. You can check the progress of that by going here and entering your domain. You want to see as many ticks as possible.
More importantly, take this time to grab yourself a little break before we move on.
SSH Client?
Before we more onto the next stage - you need an SSH client. If you're using MacOS, you're in luck with the built in terminal. If you're using Windows, then download a free piece of SSH software called Putty.
Part 2: Connecting to the server
Start your SSH client and connect to your server by typing:
ssh [email protected]
NOTE: Change domain.com to your domain
You'll see a warning if it's the first time you're connecting to the server:
The authenticity of host 'scserver.host (45.32.187.239)' can't be established. ECDSA key fingerprint is SHA256:HKcFHRW5AOO7cNBK85/yfRudRLBHnh737MFpxqrhN3c. Are you sure you want to continue connecting (yes/no)?
enter 'yes' and hit return. This will add your domain to the list of known hosts. You'll then be asked to enter your password from the password which was displayed when you clicked on the eye icon earlier. NOTE: You'll not see any typing when you're entering a password via SSH
If you've got a really bad memory like me, then it's maybe a good idea to change your password. Once you've logged in type the following:
passwd
You'll be prompted to enter a new password for the 'root' user. Enter a new password and hit return. You'll then be asked to enter your new password, retype your new password and hit return. If you've been successful, you'll see something similar to the following:
[root@codius ~]# passwd Changing password for user root. New password: Retype new password: passwd: all authentication tokens updated successfully.
The next stage of the process is following a modified version of an article created by Stefan which can be found here. I've modified it from the original as there seems to be a few issues with a lot of users, and with a few tweaks to the installation, these can be avoided. So, let's begin!
Very Important : Setup your hostname correctly.
Yes, we did set this up when we were setting up our VPS in Vultr, but by running uname -n we can verify the hostname is correct. If it is correct... cool beans! However, if you need to change it, simply paste the following:
hostnamectl set-hostname codius.scserver.host
- replacing 'codius.scserver.host' with your own hostname.
The Three Amigos
There are 3 components required to run a Codius Host.
- Hyperd — Handles virtualization and hardware isolation of code
- Moneyd — Allows the sending and receiving of payments on Interledger
- Codiusd — Exposes endpoints that allow developers to upload code to the host and launch pods for them.
Now we know what they are and what they do... it's time to install them.
Install Hyperd:
Hyperd allows the host to run uploaded code in a hardware-isolated pod, which then allocates containers for uploaded code when it is called. Copy and paste the following into your SSH client:
yum install -y gcc-c++ make
After this completes, copy and paste the following:
curl -sSl https://coiltest.s3.amazonaws.com/upload/latest/hyper-bootstrap.sh | bash
This will install all of our RPM dependencies for NodeJS and hyperd, as well as automatically forward ports from the hyperd pods. It will also launch hyperd and allow you to use the hypercli command line interface. Once installation is complete, you should see something like this:
Complete!
Start hyperd service
Redirecting to /bin/systemctl start hyperd.service
hyperd is running.
----------------------------------------------------
To see how to use hyperctl: sudo hyperctl help
To manage hyperd service: sudo service hyperd {start|stop|restart|status}
To get more information: http://hyper.sh
Note: To check on the status, you can type: systemctl status hyperd Once you see this, the install has gone well and you're ready to move on.
Install Moneyd:
Moneyd is a daemon that allows a host to send & receive payments over Interledger. In this setup it will be installed and configured to make payments with XRP but plugins for Ethereum and other blockchains are being worked on. Keep an eye on the current list of uplinks. Copy and paste the following into your SSH client:
curl --silent --location https://rpm.nodesource.com/setup_10.x | bash -
Once complete, copy and paste the following:
yum install -y nodejs
Again, once this completes, paste the final part:
yum install -y https://s3.us-east-2.amazonaws.com/codius-bucket/moneyd-xrp-4.0.0-1.x86_64.rpm
This takes a little longer - so if you've not finished you're [insert drink of choice] you've a few minutes to get a sip. Once the install completes, you're ready to move onto the next step which is configuring moneyd. Remember the XRP Secret Key we talked about at the start?... you're going to need this any second now ;)
Paste the following:
sudo moneyd xrp:configure
You'll then be asked to enter your XRP Secret. If you still haven't got one, then you need it before we can proceed further. Remeber, this wallet NEEDS to be funded with 30 XRP to be safe as I mentioned earlier.
Enter your XRP secret key and hit enter. Once done, you should see the secret key you've just entered displayed. Finally to complete this stage, we need to start the process. This can be done by typing:
systemctl start moneyd-xrp
Note: To check on the status, you can type: systemctl status moneyd-xrp
Install Codiusd:
Codiusd is the server-side component of Codius, which exposes endpoints that allow users to upload code and provision containers for them. It also proxies requests to pods that it is currently hosting.
Copy and paste the following:
yum install -y git
Once this is complete, move onto copying and pasting the following:
npm install -g codiusd --unsafe-perm
The next stage is to create a file called codiusd.service which we will save in /etc/systemd/system - To do this, copy and paste the following:
nano /etc/systemd/system/codiusd.service
This will open a blank editor. Copy and paste the following into the editor window:
[Unit]
Description=Codiusd
After=network.target nss-lookup.target
[Service]
ExecStart=/usr/bin/npm start
Environment="DEBUG=*"
Environment="CODIUS_PUBLIC_URI=https://codius.example.com"
Environment="CODIUS_XRP_PER_MONTH=10"
WorkingDirectory=/usr/lib/node_modules/codiusd
Restart=always
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=codiusd
User=root
Group=root
[Install]
WantedBy=multi-user.target
Once this is done, exit the editor by hitting Crtl+X on MacOS. It will ask you if you would like to save, select y for Yes and hit enter. Again, it will then ask you where you would like to save it - however as we specified that in the earlier command, we can simply hit enter.
Some of you may notice the following line in the code we've just pasted:
Environment="CODIUS_PUBLIC_URI=https://codius.example.com"
and you'll be right knowing this would cause an issue if we didn't change it. We need to replace this with our information.
Copy and paste the following to use the hostname we setup at the start:
sed -i s/codius.example.com/`uname -n`/g /etc/systemd/system/codiusd.service
This will change that line to use the hostname which we setup at the start of the process. We now need to Enable and Start the Codiusd process. You can Enable codiusd by running the following:
systemctl enable codiusd
This will create a symlink to /etc/systemd/system/codiusd.service
Finally, start codiusd by running:
systemctl start codiusd
Note: To check on the status, you can type: systemctl status codiusd
Your codiusd server will now be running on port 3000. Manifests can be uploaded via endpoints at this address. We will write more on this soon so stay tuned.
In the meantime, we're not quite finished yet. Time for another break?
Setting up DNS via Vultr:
Remember that link I said you should bookmark earlier on for when we need to work on the DNS records for the server? Lucky for you, no need to scroll back up and try and find it. Head to the Vultr DNS page and select your server.
In order to run Codius, we need a primary hostname for our Codius host and we also need any subdomains to point to our host. For example, if your domain is scserver.host, you need to point codius.scserver.host to your codius host, including any subdomains like xyz.codius.scserver.host, amazing.codius.scserver.host, yougettheidea.codius.scserver.host etc. Lucky for us, thats easy to achieve that, we simply create two A records. Using Vultr, this is done by entering codius in the name field, and your server IP address in the Data field (in my case 45.32.187.239). Change the TTL from 3600 to 300 and hit the '+' button. Once you've done this, you need to do the same again but enter *.codius in the name field - taking notice of the wildcard before the .
Once we've made these changes, the next stage before we continue is to ping the server to ensure we've made the correct changes.
You can do this by typing:
ping codius.scserver.host
You should see a result like this:
Next, try again but with a random start of the URL. for example:
ping englandfortheworldcup.codius.scserver.host
Again, you should see a result. (Maybe not the World Cup result I'm hoping for but who knows) Once you've successfully pinged the server, it means we can move onto the next stage.
Getting a SSL Certificate... for FREE!
Remember when SSL certificates used to be expensive? Remember when needing a wildcard SSL would almost need a trip to the bank and a remortgage of your home. OK so they weren't THAT bad - but things have changed and we can now get them for free! #Bonus!
The certificates we'll be setting up are provided by an amazing company called Let's Encrypt. I encourage everyone to donate however much they have spare to support this awesome service. You can donate by heading here.
The first thing we need to do is download certbot and install some dependencies. We do this by copying and pasting the following:
yum install -y git
git clone https://github.com/certbot/certbot
cd certbot
git checkout v0.23.0
./certbot-auto -n --os-packages-only
This next one can take a little longer to run but don't worry:
./tools/venv.sh
ln -s `pwd`/venv/bin/certbot /usr/local/bin/certbot
After this is done, we're ready to request our Certificate. When you copy and paste the next command, you'll be asked a few different things. Just make sure you follow the prompts and replace the details with your own ;)
certbot -d `uname -n` -d *.`uname -n` --manual --preferred-challenges dns-01 --server https://acme-v02.api.letsencrypt.org/directory certonly
During the setup process, Certbot will:
- Ask you for your email address
- Ask you to agree to the Terms of Service for Let’s Encrypt
- Ask you if you want to get spam important messages from EFF
- Ask you if you’re ok with your IP being logged publicly
- Ask you to add a TXT record for _acme-challenge.codius.scserver.host
- Ask you to add a second TXT record for _acme-challenge.codius.scserver.host
Once the records are added, your DNS will look something like this:
Once complete, the terminal will show something similar to this:
One more thing to setup (and a port to open!)
Setting up the NGINX Web Server
Now we need to set up Nginx which will act as a reverse proxy for our Codius host. Nginx will receive any incoming traffic and forward it to Codiusd. The first step for installing Nginx on CentOS 7 is to enable the EPEL repository. Copy and paste the following:
yum install -y epel-release
Then it's time to install NGINX. Again, copy and paste the following, one line at a time:
yum install -y nginx
systemctl enable nginx
echo 'return 301 https://$host$request_uri;' > /etc/nginx/default.d/ssl-redirect.conf
This next part takes a long time, but I suppose it looks a little interesting watching the dots move quickly and guessing where the next + sign will be. Copy and paste this:
openssl dhparam -out /etc/nginx/dhparam.pem 2048
Once that's complete, to configure Nginx as a reverse proxy for Codius, we need to create a file named codius.conf and save it in the /etc/nginx/conf.d/ directory. We can do this by typing the following:
nano /etc/nginx/conf.d/codius.conf
Copy and paste the following:
server {
listen 443 ssl;
ssl_certificate /etc/letsencrypt/live/codius.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/codius.example.com/privkey.pem;
ssl_protocols TLSv1.2;
ssl_prefer_server_ciphers on;
ssl_dhparam /etc/nginx/dhparam.pem;
ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384;
ssl_ecdh_curve secp384r1;
ssl_session_timeout 10m;
ssl_session_cache shared:SSL:10m;
ssl_session_tickets off;
ssl_stapling on;
ssl_stapling_verify on;
resolver 1.1.1.1 1.0.0.1 valid=300s;
resolver_timeout 5s;
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload";
add_header X-Frame-Options DENY;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
}
}
Once done, as we did before, hit Ctrl+X, then hit Y to save and save with the suggested filename and location.
As before... we need to change the hostname to use our own:
sed -i s/codius.example.com/`uname -n`/g /etc/nginx/conf.d/codius.conf
Finally, we need to make sure that SElinux is set to allow Nginx to act as a proxy. Copy and paste the following:
setsebool -P httpd_can_network_connect 1
NOTE: If you see setsebool: SELinux is disabled. This is fine and nothing to worry about.
Finally, we need to start NGINX:
systemctl start nginx
Note: To check on the status, you can type: systemctl status nginx
The Firewall Problem
There's been a lot of users on the Gitter pages struggling at this point. They're getting connection refused messages and it seems to be a common thing. However, it's all to do with their firewall and the firewall settings. We need to make a few changes to allow https connections.
NOTE: Thanks to Jason Grissom for helping me out with this. Awesome job!
Copy and paste the following one line at a time.
systemctl start firewalld
firewall-cmd --permanent --add-service=https
firewall-cmd --reload
Now everything is done, all that's left to do is check your work. You can look at the version of Codius which is currently running on your server and some peers which are connected. Obviously, replace my domain with your domain.
https://codius.scserver.host/version - Checkout your Codius version
https://codius.scserver.host/peers - See some of the peers connected
The next stage is to publish your very own smart contract to your host - and I'm going to be writing an article about that very soon.
Thanks,
Paul
