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

From Freeside
Jump to: navigation, search
m (fix mod_ssl link Packages)
(all spammers must die)
 
(78 intermediate revisions by 18 users not shown)
Line 2: Line 2:
  
 
Install Freeside on a firewalled, private server, not a public (web, RADIUS, etc.) server.
 
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 ==
 
== Prerequisites ==
Line 7: Line 9:
 
=== Packages ===
 
=== Packages ===
  
* [http://www.perl.org/ Perl], minimum version 5.8.0 (5.8.3 for RT?)
+
* [http://www.perl.org/ Perl], minimum version 5.8.4
* [http://httpd.apache.org/ Apache], version 1.3 ([http://www.modssl.org/ mod_ssl] highly recommended)
+
* [http://httpd.apache.org/ Apache], SSL highly recommended)
* [http://perl.apache.org/ mod_perl], version 1.29 (if compiling your own mod_perl, make sure you set the EVERYTHING=1 compile-time option)
+
* [http://perl.apache.org/ 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 [http://search.cpan.org/search?mode=module&query=DBD%3A%3A supported] by Perl's [http://dbi.perl.org/ DBI].  
 
* A '''transactional''' database engine [http://search.cpan.org/search?mode=module&query=DBD%3A%3A supported] by Perl's [http://dbi.perl.org/ DBI].  
** [http://www.postgresql.org PostgreSQL] is recommended (v7.2 or later, 7.4 or later recommended).  
+
** [http://www.postgresql.org PostgreSQL] is recommended (v7.2 or later, v7.4 or later recommended).  
** [http://www.mysql.com 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.
+
** [http://www.mysql.com MySQL] (v4.1 or later, v5 recommended) is supported starting with Freeside 1.7.3.  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 MySQL  or any other DBI-supported database.''
+
''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.''
  
 
* teTeX and Ghostscript (included with most distributions) (Optional, enables typeset invoices)
 
* teTeX and Ghostscript (included with most distributions) (Optional, enables typeset invoices)
Line 30: Line 34:
 
* [http://search.cpan.org/dist/Text-Template Text::Template]
 
* [http://search.cpan.org/dist/Text-Template Text::Template]
 
* [http://search.cpan.org/dist/DBI DBI]
 
* [http://search.cpan.org/dist/DBI DBI]
** [http://search.cpan.org/search?mode=module&query=DBD%3A%3A DBD] for your database engine ([http://search.cpan.org/dist/DBD-Pg DBD::Pg] for PostgreSQL)
+
** [http://search.cpan.org/search?mode=module&query=DBD%3A%3A DBD] for your database engine ([http://search.cpan.org/dist/DBD-Pg DBD::Pg] for PostgreSQL or [http://search.cpan.org/dist/DBD-mysql DBD::mysql] for MySQL)
* [http://search.cpan.org/dist/MailTools MailTools] (CPAN: "install Mail::Internet")
+
* [http://search.cpan.org/dist/MailTools MailTools] (CPAN: "install Mail::Internet") (Freeside v1.7.2: use MailTools v1.77, not later versions) (Freeside 1.7.3: use MailTools v2.00 or later)
* [http://search.cpan.org/dist/MIME-tools MIME::Tools]
+
* [http://search.cpan.org/dist/MIME-tools MIME::Tools] (Note: do not use v5.423.  Versions from 5.424 and later should be okay, as well as versions from 5.420 and older. Status of 5.421 and 5.422 is unknown.)
 
* [http://search.cpan.org/dist/TimeDate TimeDate] (CPAN: "install Date::Format")
 
* [http://search.cpan.org/dist/TimeDate TimeDate] (CPAN: "install Date::Format")
 
* [http://search.cpan.org/dist/Locale-Codes Locale-Codes] (CPAN: "install Locale::Country")
 
* [http://search.cpan.org/dist/Locale-Codes Locale-Codes] (CPAN: "install Locale::Country")
 +
* [http://search.cpan.org/dist/DateTime DateTime]
  
 
==== Modules of Indeterminate Popularity ====
 
==== Modules of Indeterminate Popularity ====
Line 45: Line 50:
 
* [http://search.cpan.org/dist/Frontier-RPC Frontier::RPC2]
 
* [http://search.cpan.org/dist/Frontier-RPC Frontier::RPC2]
 
* [http://search.cpan.org/dist/Term-ReadKey Term::ReadKey]
 
* [http://search.cpan.org/dist/Term-ReadKey Term::ReadKey]
 +
* [http://search.cpan.org/dist/DateManip Date::Manip]
 +
* [http://search.cpan.org/dist/DateTime-Format-Strptime DateTime::Format::Strptime]
 +
* [http://search.cpan.org/dist/Text-CSV_XS Text::CSV_XS]
 +
* [http://search.cpan.org/dist/Spreadsheet-WriteExcel Spreadsheet::WriteExcel]
 +
* [http://search.cpan.org/dist/Number-Format Number::Format]
  
==== Less common modules probably not included in anything but Debian? ====
+
==== Less common modules ====
  
 
* [http://search.cpan.org/dist/Business-CreditCard Business::CreditCard]
 
* [http://search.cpan.org/dist/Business-CreditCard Business::CreditCard]
 
* [http://search.cpan.org/dist/Net-Whois-Raw Net::Whois::Raw]
 
* [http://search.cpan.org/dist/Net-Whois-Raw Net::Whois::Raw]
* [http://search.cpan.org/dist/DBIx-DBSchema DBIx::DBSchema]
+
* [http://search.cpan.org/dist/DBIx-DBSchema DBIx::DBSchema] (Freeside v1.7.2: use DBIx::DBSchema v0.32, not later versions) (Freeside 1.7.3: use current DBIx::DBSchema)
 
* [http://search.cpan.org/dist/Tie-IxHash Tie::IxHash]
 
* [http://search.cpan.org/dist/Tie-IxHash Tie::IxHash]
 
* [http://search.cpan.org/dist/Crypt::PasswdMD5 Crypt::PasswdMD5]
 
* [http://search.cpan.org/dist/Crypt::PasswdMD5 Crypt::PasswdMD5]
 
* [http://search.cpan.org/dist/Time-Duration Time::Duration]
 
* [http://search.cpan.org/dist/Time-Duration Time::Duration]
 
* [http://search.cpan.org/dist/File-CounterFile File::CounterFile]
 
* [http://search.cpan.org/dist/File-CounterFile File::CounterFile]
 +
* [http://search.cpan.org/dist/IPC-Run IPC::Run]
 
* [http://search.cpan.org/dist/IPC-Run3 IPC::Run3]
 
* [http://search.cpan.org/dist/IPC-Run3 IPC::Run3]
 
* [http://search.cpan.org/dist/Net-SSH Net::SSH]
 
* [http://search.cpan.org/dist/Net-SSH Net::SSH]
Line 60: Line 71:
 
* [http://search.cpan.org/dist/JSON JSON]
 
* [http://search.cpan.org/dist/JSON JSON]
 
* [http://search.cpan.org/dist/HTML-Widgets-SelectLayers HTML::Widgets::SelectLayers]
 
* [http://search.cpan.org/dist/HTML-Widgets-SelectLayers HTML::Widgets::SelectLayers]
 +
* [http://search.cpan.org/dist/Color-Scheme Color::Scheme]
 +
* [http://search.cpan.org/dist/Lingua-EN-NameParse Lingua::EN::NameParse]
 +
* [http://search.cpan.org/dist/Lingua-EN-Inflect Lingua::EN::Inflect]
  
 
==== Optional modules ====
 
==== Optional modules ====
Line 65: Line 79:
 
* [http://search.cpan.org/dist/Fax-Hylafax-Client Fax::Hylafax::Client] ''(Required if faxing invoices)''
 
* [http://search.cpan.org/dist/Fax-Hylafax-Client Fax::Hylafax::Client] ''(Required if faxing invoices)''
 
* [http://search.cpan.org/dist/Apache-DBI Apache::DBI] ''(recommended for better web interface performance)''
 
* [http://search.cpan.org/dist/Apache-DBI Apache::DBI] ''(recommended for better web interface performance)''
 
  
 
== Installation ==
 
== Installation ==
Line 71: Line 84:
 
* Add the user and group `freeside' to your system.
 
* Add the user and group `freeside' to your system.
 
* Allow the freeside user full access to the freeside database.  
 
* Allow the freeside user full access to the freeside database.  
** with PostgreSQL<pre><nowiki>
+
with PostgreSQL
 +
<pre>
 
$ su postgres (pgsql on some distributions)
 
$ su postgres (pgsql on some distributions)
 
$ createuser -P freeside
 
$ createuser -P freeside
Line 79: Line 93:
 
Shall the new user be allowed to create more new users? (y/n) n
 
Shall the new user be allowed to create more new users? (y/n) n
 
CREATE USER
 
CREATE USER
</nowiki></pre>
+
</pre>
** or with MySQL:<pre><nowiki>
+
or with Postgresql 8.3
 +
<pre>
 +
[ 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
 +
</pre>
 +
or with MySQL:
 +
<pre>
 
$ mysqladmin -u root password 'set_a_root_database_password'
 
$ mysqladmin -u root password 'set_a_root_database_password'
 
$ mysql -u root -p
 
$ 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';
 
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,DROP on freeside.* TO freeside@localhost IDENTIFIED BY 'set_a_freeside_database_password';
</nowiki></pre>
+
</pre>
  
 
*Edit the top-level Makefile:  
 
*Edit the top-level Makefile:  
Line 91: Line 116:
  
 
* Add the freeside database to your database engine:  
 
* Add the freeside database to your database engine:  
** with Postgres: <pre><nowiki>
+
with Postgres:  
 +
<pre>
 
$ su freeside
 
$ su freeside
 
$ createdb -E sql_ascii freeside
 
$ createdb -E sql_ascii freeside
</nowiki></pre>
+
</pre>
** or with MySQL: <pre><nowiki>
+
or with Postgres 8.3:
 +
<pre>
 +
$ su freeside
 +
$ createdb -E LATIN1 freeside
 +
</pre>
 +
or with MySQL:  
 +
<pre>
 
$ mysqladmin -u freeside -p create freeside  
 
$ mysqladmin -u freeside -p create freeside  
</nowiki></pre>
+
</pre>
  
* Build and install the Perl modules: <pre><nowiki>
+
* Build and install the Perl modules:  
 +
<pre>
 
$ make perl-modules
 
$ make perl-modules
 
$ su
 
$ su
 
# make install-perl-modules
 
# make install-perl-modules
</nowiki></pre>
+
</pre>
  
* Create the necessary configuration files: <pre><nowiki>
+
* Create the necessary configuration files:
 +
<pre>
 
$ su
 
$ su
 
# make create-config
 
# make create-config
</nowiki></pre>
+
</pre>
  
* Run a '''separate''' iteration of Apache[-SSL] with mod_perl enabled '''as the freeside user'''.
+
* Ensure Apache has mod_perl enabled and is set to run as <code>User freeside</code>.  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 <code>FREESIDE_DOCUMENT_ROOT</code>.  
 
* Edit the Makefile and set <code>FREESIDE_DOCUMENT_ROOT</code>.  
  
* Run <code>make install-docs</code>
+
* Run  
 +
<pre>
 +
# make install-docs
 +
</pre>
 +
 
 +
* Edit the Makefile and set <code>APACHE_VERSION</code> 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 <code>APACHE_CONF</code> 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 "<code>Include /etc/apache/conf.d</code>" to httpd.conf.)
 +
 
 +
* Run
 +
<pre>
 +
# make install-apache
 +
</pre>
  
* Configure Apache: <pre><nowiki>
+
''Note: Do not attempt to restart Apache (httpd) yet.''
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>
 
</nowiki></pre>
 
 
* Restrict access to this web interface - see the [http://httpd.apache.org/docs/misc/FAQ.html#user-authentication Apache documentation on user authentication]. For example, to configure user authentication with [http://httpd.apache.org/docs/mod/mod_auth.html mod_auth] (flat files), add something like the following to your Apache httpd.conf file, adjusting for your actual paths: <pre><nowiki>
 
#your freeside document root
 
<Directory /var/www/freeside>
 
AuthName Freeside
 
AuthType Basic
 
AuthUserFile /usr/local/etc/freeside/htpasswd
 
require valid-user
 
</Directory>
 
</nowiki></pre>
 
  
* 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):
+
* As the freeside UNIX user, run <code>freeside-setup -d your.domain.name</code> to create the database tables and initial data.
** First user: <pre><nowiki>
+
<pre>
$ su
+
$ su freeside
# freeside-adduser -c -h /usr/local/etc/freeside/htpasswd username
+
$ freeside-setup -d example.com
</nowiki></pre>
+
</pre>
** Additional users: <pre><nowiki>
 
$ su
 
# freeside-adduser -h /usr/local/etc/freeside/htpasswd username
 
</nowiki></pre>
 
''(using other auth types, add each user to your Apache authentication and then run: freeside-adduser username) ''
 
  
* Create the Freeside system users: <pre><nowiki>
+
* Create the Freeside system users:  
$ su
+
<pre>
# freeside-adduser fs_queue
+
$ su freeside
# freeside-adduser fs_daily
+
$ freeside-adduser -g 1 fs_queue
# freeside-adduser fs_selfservice
+
$ freeside-adduser -g 1 fs_daily
</nowiki></pre>
+
$ freeside-adduser -g 1 fs_selfservice
 +
</pre>
  
* 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: <pre><nowiki>
+
* Create one or more Freeside users (your internal sales/tech folks, not customer accounts):
 +
<pre>
 
$ su freeside
 
$ su freeside
$ freeside-setup -d example.com username
+
$ freeside-adduser -g 1 username
</nowiki></pre>
+
$ htpasswd /usr/local/etc/freeside/htpasswd username
 +
Password:
 +
</pre>
 +
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 <code>INIT_FILE</code> with the appropriate location on your system and <code>QUEUED_USER</code> with the username of a Freeside user you created above, and run <code>make install-init</code>)  
 
* 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 <code>INIT_FILE</code> with the appropriate location on your system and <code>QUEUED_USER</code> with the username of a Freeside user you created above, and run <code>make install-init</code>)  
  
* Now proceed to the initial administration of your installation.
+
* Either [[Freeside:1.7:Documentation:RT_Installation|install the integrated RT ticketing system]], or delete the <code>ticket_system</code> file from your configuration directory (<code>/usr/local/etc/freeside/conf.''datasrc''</code>).
 +
 
 +
* Restart Apache (httpd) and log into the web interface using the username and password you entered above.
 +
 
 +
* Now proceed to the initial [[Freeside:1.7:Documentation:Administration|administration]] of your installation.

Latest revision as of 13:52, 20 July 2009

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.4
  • 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, v7.4 or later recommended).
    • MySQL (v4.1 or later, v5 recommended) is supported starting with Freeside 1.7.3. 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.

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

Perl modules

Popular modules you might want to check your distribution for

Modules of Indeterminate Popularity

Less common modules

Optional modules

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 Postgresql 8.3

[ 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';
  • 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 Postgres 8.3:

$ su freeside
$ createdb -E LATIN1 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_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.)
  • Run
# make install-apache

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

  • 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 and QUEUED_USER with the username of a Freeside user you created above, and run make install-init)
  • Restart Apache (httpd) and log into the web interface using the username and password you entered above.