Truledger Server Setup & Maintenance

This page tells you how to start up and initialize a Truledger server. It is only useful for people who want to run a Truledger. If you just want to access somebody else's Truledger server, you'll likely find the client documenation to be more useful.


If you just want to learn the Truledger server by doing, follow the directions in the gray boxes titled "Summary".


Initializing the Server Database
Backing Up the Server Database


Follow the Client installation instructions. The Truledger binaries contain both client and server code.

Choose a directory in which the databases will be installed. When you run the executable, it will create a "truledger-dbs" sub-directory of the current directory, and, inside that, "clientdb" and "serverdb" sub-directories.

The Truledger application has a number of command line arguments, none of which are in the client documentation. Here's the help output (in 32-bit Linux):

$ ./truledger-lx86cl -h
Usage is: ./truledger-lx86cl [-p port] [--key keyfile --cert certfile] [--nonsslport nonsslport] [--uid uid --gid gid]
port defaults to 8782, unless keyfile & certfile are included, then 8783.
If port defaults to 8783, then nonsslport defaults to 8782,
otherwise the application doesn't listen on a non-ssl port.
keyfile is the path to an SSL private key file.
certfile is the path to an SSL certificate file.
uid & gid are the user id and group id to change to after listening on the port.

Command line parameters
portThe port to listen on.
keyfilePath, absolute or relative to working directory, of SSL private key file.
certfilePath, absolute or relative to working directory, of SSL certificate file.
nonsslportIf keyfile and certfile are specified, port will be listened on for an SSL connection. If you also want to listen for non-SSL connections, nonsslport says which port to listen on for that. Attempts to access the client or server active pages on nonsslport, will redirect to the SSL port, using HTTPS. Static web pages (see below) will remain unencrypted.
uid / gidPorts less than 1024 (e.g. the HTTP default, 80, and the HTTPS default, 443) are privileged. You need to run the Truledger application as root in order to use them. If you do that, and specify uid and gid, the app will change its group id and user id to these after starting to listen on port (and nonsslport). This allows you to use a privileged port, but not run as root. Another way to do that is to run the Truledger server on non-priveleged port(s) and use Apach mod_proxy or Pound or another reverse proxy to listen on the privileged port(s).

Since you'll want the server to keep running after you've logged off of the server machine, you'll need to either start it in the startup scripts, or use nohup or screen.

Summary - Server Startup

$ cd ~/truledger
$ screen -S truledger
$ sudo ./truledger-lx86cl -p 443 --key key.pem --cert cert.pem --nonsslport 80 --uid `id -u` --gid `id -g`
Client web server started on port 80
Web address: http://localhost/

Initializing the Server Database

Starting the Truledger application enables the its web server to listen on the port(s) you specified, and the client web server will be fully functional, but the server database needs to be initialized before it can serve as a Truledger server. To do that, go to the "Register a new account" screen, and create an account, with a blank "Coupon", for the server administrator.

Now click the "Admin" link at the top of the page, and enter a "Server Name", "Server URL", "Server Passphrase" and "Verification". Enter the passphrase you used for the admin account in "Admin Passphrase" and "Verification".

Admin init server

Press the "Start Server" button. The server's 3072-bit private key will be created (and a new admin private key if you used a new passphrase for that), both the server and the administrator accounts will be added to the client database, with each other as contacts, and 200,000 usage tokens will be transferred to the admin account. Because the server's account doesn't keep an inbox or an outbox, and because customers are not allowed to spend to it, I recommend that you distribute usage tokens, and server-issued assets, from the admin account. Use the server account only to give the admin account more usage tokens, and to administer the server server.

Admin after init

Above is the "Admin" page after the server has been initialized. When there's a server database, only the server can get to the "Admin" page, and new client accounts require a server coupon, or an existing server account. Before that, anyone can create new accounts and go to the "Admin" page.

The "Shut down web server" button stops the web server and exits the Truledger application. The "Stop Server" button stops the server from serving web requests, but leaves the client web server running to serve client requests. I explain the "Start Backup" and "Enable backup mode" buttons below.

When the server is running, it responds to server requests via the URL "/?msg=...", to client requests via "/client/...", and serves static web pages in the "www" sub-directory of the working directory ( serves the file "www/foo.html"). Only "index.html" is supported as a directory index file, but you can include any other static HTML, images, or JavaScript files you desire. That's how this page is being served. There is currently no support for customizing the client web pages, but you can do anything you want for the static HTML site.

When you first start the Truledger application, it serves only client web requests. To start the server server, you need to log in as the server. I do this by logging into the server machine with SSH, then using Links in that terminal window to log in to the server. Lynx would also work, or ELinks. Or, if your server has SSL, you could log in with a regular web browser.

Summary - Server Initialization

Backing Up the Server Database

Since you'll be storing claims to valuable assets in your Truledger database, you'll probably want to back it up regularly. You can do this by using any file backup mechanism on the "truledger-dbs" directory, or you can set up a backup server, and let Truledger back itself up, as changes are made. This section tells you how to do the latter.

First, copy the "truledger-dbs" directory to the backup machine. Then start the Truledger application on that machine, and log in to the client with the server's passphrase. Go to the "Admin" page. Enable backup mode by pressing the "Enable backup mode" button (see screenshot above). You'll see this:

Backup Mode Enabled

Now, on your main server, log in as the server, go to the "Admin" page, enter the URL for the backup server as the "Backup Server URL", fill in the "Notification Email" if you want to be notified of problems with the backup, and press the "Start Backup" button. You'll get an error if it can't reach the backup server. Otherwise, you'll see:

Backup Running

If you specified a notification email address, you'll get an email when you start the backup server, every ten minutes while it's having a problem backing up, and when it stops having a problem.

If you press the "Stop Backup" button, the entire database will be backed up the next time you enable backup. If, on the other hand, you press the "Shut down web server" button, to stop the server for maintenance or Truledger application upgrade, it will start backing up automatically the next time you start the server, from wherever it left off when you stopped it.

Summary - Backup

Live long and prosper!

Copyright © 2009-2010 Bill St. Clair, All Rights Reserved