Freeside:1.7:Documentation:Installation
Contents
Introduction
Install Freeside on a firewalled, private server, not a public (web, RADIUS, etc.) server.
Please note that these are the 1.7 installation instructions. Do not attempt to use them to install 1.5/1.6, or edit them to correct differences with those releases.
Prerequisites
Packages
- Perl, minimum version 5.8.3 (or minimum version 5.8.0 if the integrated RT is turned off)
- Apache, SSL highly recommended
- mod_perl
- mod_perl v2 is now supported.
- 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
- Ensure Apache has mod_perl enabled and is set to 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
.
- Run
make install-docs
- 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.)
- Run
make install-apache
- 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
- 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 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.
- 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.