FREE logo

Quick Links

Aims of the project

Download
Get Involved
Documentation
- Getting Started
- RTServer
- ERServer
- FreeClient
- Free.util
- Running Elections
- JavaDoc Docs

Contact

FREE Home
 
GETTING STARTED

Phew! You've just downloaded all the stuff: a Java Compiler and FREE. Thanks for going to the trouble.

Firstly set up the Java compiler, it should have full instructions included with it. Then uncompress the FREE archive, being sure that it unpacks into all the right directories.

The correct directory structure for FREE is:

Free-1.x.x
|
|-Free
|-FreeClient
|-ERServer
|-FreeTest
|-Util
|-Docs
|

They may be some extra directories, but these are the key ones. Make sure you read README and INSTALL before going any further.

Done? Good, now let's do the fun stuff. We're going to start rooting around in the code of FREE. You'll need a good text editor, such as Programmer's File Editor (Windows) or BBEdit (MacOS) or Emacs (UNIX).

First steps in the FREE code base

Prior to version 1.4 of FREE this documented how to setup FREE by hand. However you now HAVE to use the FreeInstall program to create a secure installation. If you are using an older version of FREE then either upgrade or refer to the older version of this document in the Docs directory of your FREE installation. This file remains as a guide to the structure of the software and important steps you need to take once you have run FreeInstall

There are three packages, which for security reasons, are totally independent of each other (though in fact some of their code is nearly identical). Let's take a look at what they do:

Free is the package that contains the program at the very heart of the FREE system, RTServer (short for Regional or Totaller Server) this receives the votes and adds them up for a final result. This is the biggest and most complex program in FREE.

ERServer contains the ERServer (short for Electoral Roll Server) software which is the simplest program in FREE. It receives requests to authenticate voters and also registers that you have cast your vote.

FreeClient holds the code for the FreeClient which is the software the voter actually uses.

Additionally there is one package of code common to the three mentioned above:

Free.util stores common files for the FREE system.

[ There are two other packages we include but aren't strictly part of the FREE system as they don't have anything to do with running an election:

FreeTest is where the FREE Testing Suite (FTS) is kept. You only need to use this if you plan to help develop FREE.
FreeInstall is a graphical system for changing the FREE code without you needing to get your hands dirty. ]

The code is heavily commented, so open it up and take a look if you're interested - this file isn't going to repeat what's already there.

Once you've finished making changes compile all the programs (see INSTALL for more on this)... and relax. You're done! Run the programs, setup the databases (see below) then run FreeClient on any computer with Java and a connection to the Internet and you'll be able to vote!

Preparing the databases

When you run RTServer or ERServer they will automatically prepare and create the Hypersonic SQL databases. Before you can RTServer in regional mode you need to create a rtserver.keys file. But to do this you will need to populate ERServer's database with Electoral Roll information so that voters can be authorised. Here's the default way to do this in FREE - to use a different authorisation system you'll need to edit the code, so let's keep things simple:

The data is stored in a table called Roll which consists of 4 columns created with the following SQL statement:

CREATE TABLE Roll (name VARCHAR(255), code VARCHAR(255), pword VARCHAR(255), voted CHAR(1))

  • name is the name of the voter.
  • code is a unique code for this ballot only (I suggest it contains numbers and letters).
  • pword is the voter's password.
  • voted stores whether the person has voted. Should be initialised to F, FREE will set it to T when the person logs in.

To insert data open ERServer's database console (by clicking on the button in ERServer's main window) and type SQL code with the following syntax into the command box:

INSERT INTO Roll VALUES ('name', 'code', 'pword', 'F')

Click the Go button to execute the data. To check the contents of the table type:

SELECT * FROM Roll

Pretty much any SQL can be used in the database console so feel free to experiment.

Finishing off

Once the ERServer database has been populated, click the Build Keys button. When it's all done take the rtserver.keys and copy it to the default directory of your RTServer which will probably be the FREE-1.x directory. Then start the RTServer and it will read the file and automatically populate the database with encrypted, unique, single-use keys.

The vote is ready to begin.

Having problems? Take a look around the rest of this documentation and then e-mail me.

- Docs Home -

Contact - by Jason Kitcat - j-dom portal

Copyright 2000 FREE e-democracy project.

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.