Building & Running from Source

Note

Please make sure you’ve followed the instructions in Setting up viacoind before moving through this section.

This section provides information about how to install and run clearinghoused from source, using this clearinghoused build system (as an alternative to setting it up manually). This method is suitable for Linux users, as well as Windows users that want to develop/enhance clearinghoused (or just don’t want to use the binary installer).

On Windows

Prerequisites

Note

As of clearinghoused v9.34.0 due to issues with some Python modules, a 64-bit version of Python cannot be used to build Clearinghouse out-of-the-box. For time being it is recommended to use a 32-bit version of Python 3.3.5 on both the 32-bit and 64-bit version of Microsoft Windows (confirmed to work with Windows 7 SP1 x64).

Minimally required to build clearinghoused from source is the following:

If you want to be able to build the Clearinghoused installer, also download the following:

  • Grab NSIS from here – Please choose the default options during installation, and install to the default path
  • Download the NSIS SimpleService plugin from here and save the .dll file contained in that zip to your NSIS plugins directory (e.g. C:\Program Files (X86)\NSIS\plugins)
  • cx_freeze – grab the 32-bit version or 64-bit version as appropriate
  • Install a binary build of cherrypy-wsgiserver such as this (for 32-bit Python)

Installing

Note

Our install script (setup.py) requires administrator access to run (so that it can create a clearinghoused.bat file in your Windows directory). To allow for this, you must launch a command prompt as administrator. To do this under Windows 7, go to Start -> All Programs -> Accessories, then right click on Command Prompt and select “Run as administrator”. More information on this is available from this link (method 1 or 2 works fine).

After launching a DOS command window using the instructions in the note above, type the following commands:

cd C:\
git clone https://github.com/ClearingHouse/clearinghoused_build
cd clearinghoused_build
C:\Python33\python.exe setup.py

The above steps will check out the build scripts to C:\clearinghoused_build, and run the setup.py script, which will check out the newest version of clearinghoused itself from git, create a virtual environment with the required dependencies, and do other necessary tasks to integrate it into the system.

If you chose to start clearinghoused at startup automatically, the setup script will also create a shortcut to clearinghoused in your Startup group.

Upon the successful completion of this script, you can now run clearinghoused using the steps below.

Running clearinghoused built from Source

Clearinghoused does not require elevated (“administrator”) privileges to be executed and operated. After installing, open a command window and run clearinghoused in the foreground via:

clearinghoused server

You can then open up another command window and run any of clearinghoused’s other functions, for example:

clearinghoused send --source=12WQTnVbzhJRswra4TvGxq1RyhUkmiVXXm --destination=VQGZ4sCpvCgRizL5v4NniaKdZKzxBtVN3q --asset=XCH --quantity=5

For more examples, see this link.

To run the clearinghoused testsuite:

clearinghoused tests

Updating to the newest source

As the code is enhanced and improved on Github, you can refresh your local copy of the repositories like so:

cd C:\clearinghoused_build
C:\Python33\python.exe setup.py update

If, upon running clearinghoused, you get a missing dependency or some other error, you can always rerun setup.py, which will regenerate your dependencies listing to the libraries and versions as listed in pip-requirements.txt:

cd clearinghoused_build
C:\Python33\python.exe setup.py

In case of a problem, refer to the list of requirements in pip-requirements.txt above and update system as necessary. Then rerun the build script again.

Building your own Installer

Complete the instructions under Prerequisites above. Then, execute the following commands to build the installer package:

cd C:\clearinghoused_build
C:\Python33\python.exe setup.py build

If successful, you will be provided the location of the resulting installer package.

On Linux

Prerequisites

Currently, Ubuntu Linux (Server or Desktop) 12.04 LTS, 13.10, and 14.04 are supported.

Support for other distributions is a future task.

Installing

As the user you want to run clearinghoused as, launch a terminal window, and type the following:

sudo apt-get -y update
sudo apt-get -y install git-core python3
git clone https://github.com/ClearingHouse/clearinghoused_build ~/clearinghoused_build
cd ~/clearinghoused_build
sudo python3 setup.py

The setup.py script will install necessary dependencies, check out the newest version of clearinghoused itself from git, create the python environment for clearinghoused, and install an upstart script that will automatically start clearinghoused on startup.

Creating a default config

Follow the instructions listed under the Config and Logging section in ViacoinTest Additional Topics.

Running clearinghoused built from Source

After installing and creating the necessary basic config, run clearinghoused in the foreground to make sure everything works fine:

clearinghoused server

(The above assumes /usr/local/bin is in your PATH, which is where the clearinghoused symlink (which just points to the run.py script) is placed. If not, run /usr/local/bin/clearinghoused instead.

Once you’re sure it launches and runs fine, press CTRL-C to exit it, and then run clearinghoused as a background process via:

sudo service clearinghoused start

You can then open up another command window and run any of clearinghoused’s other functions, for example:

clearinghoused send --source=V2WQTnVbzhJRswra4TvGxq1RyhUkmiVXXm --destination=VQGZ4sCpvCgRizL5v4NniaKdZKzxBtVN3q --asset=XCH --quantity=5

For more examples, see this link.

To run the clearinghoused testsuite:

clearinghoused tests

Updating to the newest source

As the code is enhanced and improved on Github, you can refresh your local copy of the repositories like so:

cd ~/clearinghoused_build
sudo python3 setup.py update

Clearinghouse for Windows must also be updated from a console window started with elevated privileges.

If, upon running clearinghoused, you get a missing dependency or some other error, you can always rerun setup.py, which will regenerate your dependencies listing to the libraries and versions as listed in pip-requirements.txt:

cd ~/clearinghoused_build
sudo python3 setup.py

The same approach applies to Windows - this operation requires elevation.

Mac OS X

Mac OS support is forthcoming. (Pull requests to add such support are more than welcome!)