Freeside:1.7:Documentation:Installation
Contents
Introduction
Install Freeside on a firewalled, private server, not a public (web, RADIUS, etc.) server.
Prerequisites
Packages
- Perl, minimum version 5.8.3 (or minimum version 5.8.0 if the integrated RT is turned off)
- 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")
- HTML::Mason
- Text::Template
- DBI
- MailTools (CPAN: "install Mail::Internet")
- MIME::Tools
- TimeDate (CPAN: "install Date::Format")
- Locale-Codes (CPAN: "install Locale::Country")
- DateTime
Modules of Indeterminate Popularity
- Chart (CPAN: "install Chart::Base")
- Cache::Cache
- NetAddr::IP
- String::Approx
- Locale::SubCountry
- Frontier::RPC2
- Term::ReadKey
- Date::Manip
- DateTime::Format::Strptime
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
- Color::Scheme
- Data::Table
- Lingua::EN::NameParse
- Lingua::EN::Inflect
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 orDBI: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.
- Set DATASOURCE to your DBI data source, for example,
- 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
- 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
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. To allow the system to update passwords automatically, it is currently recommended to configure user authentication with mod_auth (flat files). Add this to your Apache httpd.conf file:
- 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):
$ 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.
- 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
- 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 andQUEUED_USER
with the username of a Freeside user you created above, and runmake install-init
)
- Now proceed to the initial administration of your installation.