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 (v7.2 or later, 7.4 or later recommended).
  • MySQL is not currently supported. Developers intersted in maintaining MySQL support are welcome to ask on the -devel mailing list; many things work, but MySQL support needs a maintainer to update it for recent (and future) changes.
  Note: the above only applies to the database used by the Freeside software itself. Freeside can integrate with RADIUS and other servers running MySQL or any other DBI-supported database.
• 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)
  • 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
  • Cache::Cache
  • NetAddr-IP
  • Chart
  • Crypt::PasswdMD5
  • Locale::SubCountry
  • Frontier::RPC
  • Text::CSV_XS
  • Spreadsheet::WriteExcel
  • IO-stringy (IO::Scalar)
  • Frontier::RPC (Frontier::RPC2)
  • MIME::Entity (MIME-tools)
  • IPC::Run3
  • Term::ReadKey
  • Fax::Hylafax::Client (Required if using FAX invoice destinations)
  • 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)
• Create the Freeside system users:

  $ su
  # freeside-adduser fs_queue
  # freeside-adduser fs_selfservice

• 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.