Difference between revisions of "Freeside:2.1:Documentation:Installation"

Latest revision as of 20:38, 16 January 2012

Introduction

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

Prerequisites

Packages

Perl, minimum version 5.8.4
Apache, SSL highly recommended)
mod_perl
- 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, v8.1 or later recommended).
- MySQL (v4.1 or later, v5 recommended) is supported. DBIx::DBSchema 0.35 or later is required.

Note: the above only applies to the database used by the Freeside software itself. Freeside can integrate with RADIUS and other servers running a different database than the backend.

TeX (teTeX / TeX Live) and Ghostscript (included with most distributions) (Optional, enables typeset invoices)

Perl modules

Popular modules

These modules are included in most distributions.

libwww-perl (CPAN: "install Bundle::LWP")
DBI
- DBD for your database engine (DBD::Pg for PostgreSQL or DBD::mysql for MySQL)
TimeDate (CPAN: "install Date::Format")
Date::Manip

Common modules

These modules are included in many distributions.

Chart (CPAN: "install Chart::Base")
Cache::Cache
DateTime
DateTime::Format::Strptime
DateTime-Format-Natural
Email::Sender
Email::Sender::Transport::SMTP::TLS
HTML::Mason
Locale-Codes (CPAN: "install Locale::Country")
Locale::SubCountry
MailTools (CPAN: "install Mail::Internet")
MIME::Tools (Note: do not use version 5.423)
NetAddr::IP
Net::Ping
Net::Ping::External
Number::Format
Spreadsheet::WriteExcel
String::Approx
Text::CSV_XS
Term::ReadKey
Text::Template

Additional modules

Optional modules

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

Note on missing modules

Prerequisites missing from 2.1 documentation? Please add them.

Download Freeside

Get the source from one of the normal places
- Open source link from the home page
- Anonymous CVS
Uncompress the tarball

Installation

System User

Add the user and group `freeside' to your system.

Database User

Allow the freeside user full access to the freeside database.

with Postgresql:

[ as postgres/pgsql user ]
$ createuser -P freeside 
Enter password for new role: 
Enter it again: 
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n

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';

Database Access

Edit the top-level Makefile:

Configure the DATASOURCE to your DBI data source
- Set the DB_TYPE (Pg or 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.
If you are not using the integrated RT ticketing system, set RT_ENABLED to 0

Database

Add the freeside database to your database engine:

with Postgres:

$ su freeside
$ createdb -E sql_ascii freeside

or with Postgres 8.3 +:

$ su freeside
$ createdb -E LATIN1 freeside

or with MySQL:

$ mysqladmin -u freeside -p create freeside

Perl Modules

Build and install the Perl modules:

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

Basic configuration Files

Create the necessary configuration files:

$ su
# make create-config

Invoice Typesetting

If you are using typeset invoices, install fslongtable.sty:

$ su
# make install-texmf

Apache & Web GUI

Configuration
- Enable mod_perl
- Run as User freeside
  - If you have other things being served by Apache on this machine (hopefully internal things), it is recommended to run a separate iteration of Apache as the freeside user.

Edit the Makefile and set FREESIDE_DOCUMENT_ROOT.

To install the web interface, run:

$ su
# make install-docs

Edit the Makefile and set APACHE_VERSION to 1 (mod_perl v1.XX), 1.99 (mod_perl v2 prereleases up to and including 1.999_21, shipped with Debian 3.1, CentOS/RHEL 4, others), or 2 (mod_perl v2 proper and prereleases 1.999_22 and later).

Edit the Makefile and set APACHE_CONF to the location of an Apache include directory (not a file). (If your Apache doesn't have an existing include directory, create one and add a line such as "Include /etc/apache/conf.d" to httpd.conf.)

To install the apache configs, run:

$ su
# make install-apache

Note: Do not attempt to restart Apache (httpd) yet.

Initialize Data

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

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

Additional System Users

Create the Freeside system users:

$ su freeside
$ freeside-adduser -g 1 fs_queue
$ freeside-adduser -g 1 fs_daily
$ freeside-adduser -g 1 fs_selfservice

Create Freeside Users

Create one or more Freeside users (your internal sales/tech folks, not customer accounts):

$ su freeside
$ freeside-adduser -g 1 username
$ htpasswd /usr/local/etc/freeside/htpasswd username
Password:

Additional users can be added using the same command or from the web interface.

Queue Daemon

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)

RT

Either install the integrated RT ticketing system, or delete the ticket_system entry from your conf table.

su freeside
psql freeside
delete from conf where name = 'ticket_system';

Finalize

Restart Apache (httpd) and log into the web interface using the username and password you entered above.

Now proceed to the initial administration of your installation.