Installation

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

Before installing, you need:

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
- 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
- JSON
- Fax::Hylafax::Client (Required if using FAX invoice destinations)
- Apache::DBI (optional but recommended for better webinterface performance)

Install the Freeside distribution:

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.

Configure Apache:

PerlModule HTML::Mason
# 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:
```
#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 -d domain.name username to create the database tables and initial data, passing the username of a Freeside user you created above:
```
$ su freeside
$ freeside-setup -d example.com 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.