Freeside:1.7:Documentation:Installation

Introduction

Install Freeside on a firewalled, private server, not a public (web, RADIUS, etc.) server.

Prerequisites

Packages

• Perl, minimum version 5.8.0 (5.8.3 for RT?)
• Apache, version 1.3 (mod_ssl highly recommended)
• mod_perl, version 1.29 (if compiling your own mod_perl, make sure you set the EVERYTHING=1 compile-time option)
• 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; most 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.

• teTeX and Ghostscript (included with most distributions) (Optional, enables typeset invoices)

Perl modules

Popular modules you might want to check your distribution for

• libnet (CPAN: "install Net::Cmd")
• libwww-perl (CPAN: "install Bundle::LWP")
  • URI
  • HTML::Tagset
  • HTML::Parser
• HTML::Mason
• Text::Template
• DBI
  • DBD for your database engine (DBD::Pg for PostgreSQL)
• MailTools (CPAN: "install Mail::Internet")
• MIME::Tools
• TimeDate (CPAN: "install Date::Format")
• Locale-Codes (CPAN: "install Locale::Country")

Modules of Indeterminate Popularity

• Chart (CPAN: "install Chart::Base")
• Cache::Cache
• NetAddr::IP
• String::Approx
• Locale::SubCountry
• Frontier::RPC2
• Term::ReadKey

Less common modules probably not included in anything but Debian?

• Business::CreditCard
• Net::Whois::Raw
• DBIx::DBSchema
• Tie::IxHash
• Crypt::PasswdMD5
• Time::Duration
• File::CounterFile
• IPC::Run3
• Net::SSH
• String::ShellQuote
• JSON
• HTML::Widgets::SelectLayers

Optional modules

• Fax::Hylafax::Client (Required if faxing invoices)
• Apache::DBI (recommended for better web interface performance)

Installation

• 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

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

• • or with MySQL:

$ mysqladmin -u freeside -p create freeside

• Build and install the Perl modules:

$ make perl-modules $ su

1. make install-perl-modules

• Create the necessary configuration files:

$ su

1. make create-config

• Run a separate iteration of Apache[-SSL] with mod_perl enabled as the freeside user.

• Edit the Makefile and set FREESIDE_DOCUMENT_ROOT.

• Run make install-docs

• Configure Apache:

PerlModule HTML::Mason

1. your freeside docuemnt root

<Directory /var/www/freeside> <Files ~ (\.cgi|\.html)> AddHandler perl-script .cgi .html PerlHandler HTML::Mason </Files> <Perl> require "/usr/local/etc/freeside/handler.pl"; </Perl> </Directory>

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

1. your freeside document root

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

• As the freeside UNIX user, run freeside-setup -d domain.name to create the database tables and initial data.

$ su freeside $ freeside-setup -d example.com

• 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

1. freeside-adduser -c -h /usr/local/etc/freeside/htpasswd username

• • Additional users:

$ su freeside

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

1. freeside-adduser fs_queue
2. freeside-adduser fs_daily
3. freeside-adduser fs_selfservice

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