In creating the XRPine I was, and still am, forced to tinker with the rippled configuration file. Coupled with the Pine board’s sporty albeit slow performance when compared to a full server, I needed something that was more responsive to play around with. In doing so I could more easily learn how use the configuration file to its fullest extent possible.
My first instinct was to search for a Linux how to guide online. Apart from Ripple’s own guide on their development website, there hasn’t been one made if you want to do it manually. Wieste made a wonderful guide to use with DigitalOcean, an online Virtual Private Server (VPS) hosting server, that walks one through setting up a validator by using Docker. Other members of the community have posted information about what makes a good validator, summarizing developer information. All of this is great, but I don’t like Docker. I have no reason to give you other than it’s not my cup of tea.
For lack of a manual guide and my inclination to do everything myself, a force of habit for someone with a learning hobby, I decided to create this guide for the community. A lot of what’s here went into setting up the XRPine, but I’ll leave the gross nuts and bolts details of that out and keep it specific to using a VPS. This just gave me the development environment.
The purpose of this blog post is to hit all the in between details for other fellow DIYers. I am not pushing my guide over anyone else’s. If you like using Docker and you just want to run a validator out of the box, then by all means. Use the guide that does just that. There are some benefits to my guide. My guide will show you how to do everything from scratch, so if you’re a developer then this is the perfect guide for setting up shop. The information is readily available on the developer site. I’m paraphrasing a good portion here in the context of setting up on a VPS, and I’ll also point out a couple hurdles you might encounter.
Step 1 - DigitalOcean - SetUp your VPS
An online subscription to a VPS with 8GB of RAM and 4vCPUs is what I need so I have acquired one of those. I’m taking advantage of the free $100 slash 60 day credit that DigitalOcean is offering to get my feet wet.
To start, go to DigitalOcean (or a VPS hosting service of your choosing) and create an account. My guide will be with respect to that hosting service .When logged in, there’s a green button that says “create” in the top right. Go there and select “Droplet”
If you’re wondering what options to pick, here’s a PDF link that’ll show you.
Here’s my configuration:
- OS: Ubuntu
- Size, Standard: 8 GB RAM, 4 vCPUs
- Backup: None
- Block Storage: None
- Region: Pick a region that you want. This is case by case.
- Additional Options: I didn’t pick any.
- SSH Keys: Leave Alone. Can do this later.
- Hostname: my-awesome-vps
- Tags: None
Step 2 - DigitalOcean - Get your IP Address
Each droplet is going to come with a public facing IP address that you’ll need to take note of. I personally prefer to log in via secure shell from my own machine. That way I don’t have to go online, log in to a website, and click 10 buttons before I can get to my VPS.
From the dashboard, click on your droplet to expand its information. Here’s an example of mine (redacted). In place of 127.0.0.1 (There’s not place like home!) you’ll have your IP address. Note it.
If you want to use the online shell to access the VPS, those three dots in the top right will give you a button to click; “Access Console”. A window will appear with a command prompt to play with. Probably a pop up blocker hazard!
Step 3 - First Log In
One may choose from any secure shell (SSH) client, such as Putty, however I found one I like called SmartTTY. Just has a few extra buttons and whistles I’ve found useful over time. You can download and install that from their website. Since there are a plethora of SSH clients to choose from, I leave it to the reader to pick on of their choosing and configure it.
To log in, check your email first. You’ll need to get your credentials. The root password is emailed to you. The password is long so happy typing!
Default User: root
Password: See email
Step 4 - Add a new user
This is just good practice. Make a new user and add it as a sudo user. On Ubuntu follow these steps:
- adduser username
- usermod -aG sudo username
After setting that new user with a new password, switch to it
- su username
Step 5 - Update Linux & Install
Now, moving toward getting ready to install rippled, one must prepared linux for it. This step might be rather lengthy since Linux can take a long time to update.
Update Linux with the following commands:
- sudo apt-get update
- sudo apt-get -y upgrade
(After your cup of coffee xD)
Install the prerequisite packages with the following commands:
- sudo apt-get -y install package
Replace package with the following packages:
git cmake pkg-config protobuf-compiler libprotobuf-dev libssl-dev wget doxygen
You may install each separately or all at once on the same line. Just separate each package with a space on the command line.
Step 6 - Download, Build, and Configure Boost
Boost is a community C++ library that is both an amazing treasure trove of useful software and also a huge pain in the neck because it is so big.
- First, navigate to your home directory; cd ~
- Download it with wget:
- Use tar to unpack it:
- tar xvzf boost_1_64_0.tar.gz
- Move into the boost directory: cd boost_1_64_0/
- Now, prepare the boost build with; ./bootstrap.sh
- After the command completes, build boost!
- ./b2 -j
I used 3 of the 4 cores to build boost on the VPS.
After Boost builds, you have to tell the OS where to find it, so you do that by setting an environment variable. Environment variables are like global labels that the OS or any program can see. You add Boost to an environment variable so the rippled software can see it when it builds later.
Here’s how I do it. On Ubuntu there is the “bashrc” file. That file executes each time the user logs in or opens a new terminal. Open that file with the editor of your choice. I use emacs because VI is not my cup of tea. If you do use emacs, you’ll have to install that too. Just follow the previous step for installing a package.
- Open the bashrc file
- emacs ~/.bashrc
- Add this line to the emacs file:
- export BOOST_ROOT=/home/USERNAME/boost_1_64_0
- For the first time, source the file. Every time you log in in the future this doesn’t need to be done.
- source ~/.bashrc
- Save and exit the file:
- Save: ctrl-x and then ctrl-s
- Exit: ctrl-x and then ctrl-c
Step 6 - Download and Build rippled
This step will clone the rippled repository and build it.
- Navigate to the home directory; cd ~
- Clone the rippled repository:
- git clone https://github.com/ripple/rippled.git
- Navigate into the rippled directory: cd rippled
- Check out the master branch:
- git checkout master
- Use CMAKE to build the software:
- Make a build directory: mkdir my_build
- cd my_build
- Run cmake to generate makefiles. cmake will tell you if anything is wrong at this point
- cmake -Dtarget=gcc.debug.unity ..
- Run the build command
- cmake --build . -- -j
Here’s where I ran into some issues. Ubuntu straight out of the release that DigitalOcean is using is version 3.5. Unfortunately, the build system will force you to use version 3.9 or higher for a clean configure.
Here’s how to handle that. We’ll need to obtain cmake, build it from source and install it.
- Navigate to the home directory: cd ~
- Use wget to obtain the latest release candidate (or stable release)
- Unpack cmake
- tar xvf cmake-3.12.0-rc2.tar.gz
- Go into the cmake directory: cd cmake-3.12.0-rc2
- Run the bootstrap; ./bootstrap
- sudo make install
After this point, go back and rerun the cmake commands for rippled. Be sure to make a new build folder!
- cmake -Dtarget=gcc.debug.unity ..
- cmake --build . -- -j
NOTE: If you’re ultimate goal is to run rippled as a validator. You will want to change your build target to the release version. If you’ve made changes and want to test them out in release. This is how that works. The debug version will be slower!
- cmake -Dtarget=gcc.release.unity ..
This time, the build should work. Here’s what a valid configuration will output
And a successful build. I love how cmake counts up to 100%!
Step 7 - Modifying Code and Version Control
Now you know the command to build. If you want to rebuild, just issue the same command and watch cmake count up again!
Using git can git a little tough at times, but fortunately you can get started with minimal effort. Go back up one folder from the “my_build” directory.
If you were here: /home/validator/rippled/my_build
Go up one directory with this command; cd ..
First things first. Set up your Github username and email;
- git config --global user.name “John Doe”
- git config --global user.email “[email protected]”
If you have a preferred editor:
- git config --global core.editor emacs
Now a nifty git command to get your current information:
- git status
You’ll just have one red folder which is the build folder. That should always stay untracked. Actually I’m surprised it’s not in the “.gitignore” which is a file with file name patterns that tells git which files to ignore completely.
Best to be on the develop branch, so we’ll checkout that one:
- git checkout develop
You can probably get away with just working on develop. You won’t be able to push to ripple’s rep but you can make commits locally and pull changes that are made remotely. To get your changes pushed then you’ll have to make a pull request.
- git add *
- git commit -m “Fancy commit message”
That wraps it up! I thought about going as far as making the guide detail how to set up with a Integrated Development Environment, such as Eclipse. I really don’t know what the community devs prefer to use. Some might prefer building on Windows in which case Visual Studio would be better. If I got some idea of what IDE developers were choosing, I’d make a guide for that.
This is half the battle. I hope Ripple updates their developer guide to account for the version issues with cmake. Getting around it isn’t hard, but it could potentially make somebody stumble. If you’re a developer, go ahead and checkout ripple’s issue list. Pick one and have at it. Who knows? Maybe some of your code might end up in the next rippled release! I hope so there are far fewer low level C/C++ devs out there than there are web developers.
Moving forward, I’ll post about the configuration steps involved with setting up rippled to run. That include the configuration file, setting up the linux service so it runs automatically and generating validator keys.
As always. Second star to the right; and Warp 6 this time!