Condorcet Internet Voting System
Copyright © 2016, Andrew C. Myers

INSTALLATION INSTRUCTIONS

1. Create a configuration file.  You will find it helpful to use
   config/sample as a template.  The configuration file specifies
   certain constants that localize the CIVS installation to your system:
   file system paths, URLs, email addresses, server names, etc.

2. Run the install script.  Assuming your working directory is the CIVS install
   directory, you would do this by invoking:

      ./install-civs config/my_config_file

   Of course, you would replace "my_config_file" with the name of the file
   you created in step 1.

   Check for any errors reported by the install script and try to
   correct them.  The most likely warning that the install script
   will report is that the $CIVSDATADIR/private_host_id file does
   not exist.  The data in this file acts as the server's private
   key.  There is no requirement on the format of this file.  It is
   suggested that you fill it with some number of randomly-generated
   bits, but English text will suffice.

3. Apache is the only explicitly supported web server, though the system
   may be able to work with other servers. The server must support content
   negotiation on languages.

   For Apache:
   * Enable the MultiViews option on at least the CIVS document directory
     ($HTMLDIR) and the CIVS CGI directory ($CGIBINDIR), and use
     the directive "AddHandler type-map .var" for both these directories.
     Also make sure the ExecCGI option is set on the CGI directory.
   * The following modules should be enabled: mod_cgi,
     mod_negotiation, mod_mime.
   * Include/enable the httpd-languages.conf file if it exists, possibly in a
     subdirectory such as extra/.
   * Add index.html.var to the DirectoryIndex option (may be in dir.conf)

   For example:

        DocumentRoot /srv/webroot/html
        <Directory /srv/webroot/html>
                Options Indexes FollowSymLinks
                AllowOverride None
                Require all granted
        </Directory>

        <Directory "/srv/webroot/html/civs">
            AddHandler type-map .var
            DirectoryIndex index.html.var

            AllowOverride None
            Options None +MultiViews
            Require all granted
        </Directory>

        ScriptAlias /cgi-bin "/srv/webroot/cgi-bin"
        <Directory "/srv/webroot/cgi-bin">
            AddHandler cgi-script .cgi .pl
            AddHandler type-map .var

            AllowOverride None
            Options None +MultiViews +ExecCGI
            Require all granted
        </Directory>

4. Install necessary Perl modules using apt-get, cpan or cpanm (cpanminus):

   For basic operation:

      HTML::TagFilter
      HTML::Parser
      HTML::Tagset
      URI::Escape
      CGI
      Net::SMTP
      Authen::SASL

   For TLS support:

      IO:Socket::SSL
      Net::SSLeay (possibly)
      Also install openssl and libssl-dev

   On a Debian-based distribution, these can be installed with:

      sudo apt install \
		libhtml-tagfilter-perl \
		libhtml-parser-perl \
		libhtml-tagset-perl \
		libcgi-pm-perl \
		libauthen-sasl-perl \
		libnet-ssleay-perl

5. Test the server installation by browsing to $CIVSURL, creating
   an election, adding yourself as a voter, opening the election,
   voting in the election, closing the election, and viewing the
   results.

Good luck!

ACKNOWLEDGEMENTS

  Several people have worked on CIVS and its design.

    Andrew Myers built the initial version of the system and has maintained it.
    Michael Clarkson designed and implemented the protocols that are used to
    protect voter identity.  He also added the ballot reporting feature and
    cleaned up the code quite a bit.

    Nate Nystrom gave good suggestions on the the user interface,  David Gamble
    helpfully critiqued the proportional representation method, and Steve
    Eppley gave useful pointers on MAM and related methods.
    Chris Benham helped with the "runoff" method.

    Localization for languages other than English was provided by other
    volunteers: Árpád Magosányi (Hungarian), Jacopo Corbetta (Italian), Pascal
    Levasseur and Michel Billard Sarakawa (French), Julian Mehnle (German), Tom
    Dromi and Roey Perlstein-Dvir (Hebrew), Benhur Stein (Portuguese),
    Danfeng Zhang (Chinese), and Chin Isradisaikul (Thai).

    Contributions and feedback are always welcome!

    Additional language support would be great if there are more
    volunteers out there. Some languages frequently used in CIVS
    polls but that are not yet supported include Spanish, Russian,
    and Norwegian. Adding support for a new language is pretty easy
    and does not require programming expertise.
