Installation

• Perl, minimum version 5.005_03. (5.8.3 for the integrated RT ticketing)
• Apache (mod_ssl or Apache-SSL highly recommended)
• mod_perl (if compiling your own mod_perl, make sure you set the EVERYTHING=1 compile-time option)
• SSH (OpenSSH is recommended. SSH Communications Security commercial SSH version 3 has been reported incompatible with Freeside.)
• rsync
• Optional, enables typeset invoices: teTeX and Ghostscript (included with most distributions).
• A transactional database engine supported by Perl's DBI.
  • PostgreSQL is recommended (v7or later).
  • MySQL MINIMUM VERSION 4.1 is untested but may work. Versions before 4.1 do not support standard SQL subqueries and are NOT SUPPORTED. MySQL's default MyISAM and ISAM table types are not supported. You must use one of the new transaction-safe table types such as InnoDB. Set it as the default table type using the --default-table-type=InnoDB mysqld command-line option or by setting default-table-type=InnoDB in the my.cnf option file.
• Perl modules (CPAN will query, download and build perl modules automatically)
  • MIME-Base64
  • Digest-MD5
  • URI
  • HTML-Tagset
  • HTML-Parser
  • libnet
  • Locale-Codes
  • Net-Whois-Raw
  • libwww-perl
  • Business-CreditCard
  • MailTools
  • TimeDate
  • DateManip
  • File-CounterFile
  • FreezeThaw
  • String-Approx
  • Text-Template
  • DBI
  • DBD for your database engine (DBD::Pg for PostgreSQL, DBD::mysql for MySQL)
  • DBIx-DBSchema
  • Net-SSH
  • String-ShellQuote
  • Net-SCP
  • HTML::Mason (recommended, enables full functionality) or Apache::ASP (deprecated, integrated RT ticketing will not be available)
  • Tie-IxHash
  • Time-Duration
  • HTML-Widgets-SelectLayers
  • Storable
  • NetAddr-IP
  • Chart
  • Crypt::PasswdMD5
  • JavaScript::RPC (JavaScript::RPC::Server::CGI)
  • Apache::DBI (optional but recommended for better webinterface performance)

• Add the user and group `freeside' to your system.
• Allow the freeside user full access to the freeside database.
  • with PostgreSQL:

    $ su postgres (pgsql on some distributions)
    $ createuser -P freeside
    Enter password for user "freeside": 
    Enter it again: 
    Shall the new user be allowed to create databases? (y/n) y
    Shall the new user be allowed to create more new users? (y/n) n
    CREATE USER

  • with MySQL:

    $ mysqladmin -u root password 'set_a_root_database_password'
    $ mysql -u root -p
    mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,DROP on freeside.* TO freeside@localhost IDENTIFIED BY 'set_a_freeside_database_password';

• Edit the top-level Makefile:
  • Set DATASOURCE to your DBI data source, for example, DBI:Pg:dbname=freeside for PostgresSQL or DBI:mysql:freeside for MySQL. See the DBI manpage and the manpage for your DBD for the exact syntax of your DBI data source.
  • Set DB_PASSWORD to the freeside database user's password.
• Add the freeside database to your database engine:
  • with Postgres:

    $ su freeside
    $ createdb -E sql_ascii freeside

  • with MySQL:

    $ mysqladmin -u freeside -p create freeside 

• Build and install the Perl modules:

  $ make perl-modules
  $ su
  # make install-perl-modules

• Create the necessary configuration files:

  $ su
  # make create-config
  

• Run a separate iteration of Apache[-SSL] with mod_perl enabled as the freeside user.
• Edit the Makefile and set TEMPLATE to asp or mason. Also set FREESIDE_DOCUMENT_ROOT.
• Run make install-docs.

• Restrict access to this web interface - see the Apache documentation on user authentication. For example, to configure user authentication with mod_auth (flat files), add something like the following to your Apache httpd.conf file, adjusting for your actual paths:

  #your freeside document root
  <Directory /var/www/freeside>
  AuthName Freeside
  AuthType Basic
  AuthUserFile /usr/local/etc/freeside/htpasswd
  require valid-user
  </Directory>
  

• Create one or more Freeside users (your internal sales/tech folks, not customer accounts). These users are setup using using Apache authentication, not UNIX user accounts. For example, using mod_auth (flat files):
  • First user:

    $ su
    $ freeside-adduser -c -h /usr/local/etc/freeside/htpasswd username

  • Additional users:

    $ su
    $ freeside-adduser -h /usr/local/etc/freeside/htpasswd username

  (using other auth types, add each user to your Apache authentication and then run: freeside-adduser username)
• As the freeside UNIX user, run freeside-setup username to create the database tables, passing the username of a Freeside user you created above:

  $ su freeside
  $ freeside-setup username
  

  Alternately, use the -s option to enable shipping addresses: freeside-setup -s username
• As the freeside UNIX user, run bin/populate-msgcat username (in the untar'ed freeside directory) to populate the message catalog, passing the username of a Freeside user you created above:

  $ su freeside
  $ cd /path/to/freeside/
  $ bin/populate-msgcat username
  

• freeside-queued was installed with the Perl modules. Start it now and ensure that is run upon system startup (Do this manually, or edit the top-level Makefile, replacing INIT_FILE with the appropriate location on your systemand QUEUED_USER with the username of a Freeside user you created above, and run make install-init)
• Now proceed to the initial administration of your installation.