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

From Freeside
Jump to: navigation, search
 
(38 intermediate revisions by 5 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.9 installation instructions.  Do not attempt to use them to install 1.7/1.8, or edit them to correct differences with those releases.
 
  
 
== Prerequisites ==
 
== Prerequisites ==
Line 20: Line 18:
 
''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.''
 
''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)
+
* TeX (teTeX / TeX Live) and Ghostscript (included with most distributions) (Optional, enables typeset invoices)
  
 
=== Perl modules ===
 
=== Perl modules ===
  
==== Popular modules you might want to check your distribution for ====
+
==== Popular modules ====
 +
 
 +
These modules are included in most distributions.
 +
<!-- reference: CentOS/RHEL 5, i.e. http://linux.mirrors.es.net/centos/5/os/x86_64/CentOS/
 +
if its there, its everywhere... right? -->
  
* [http://search.cpan.org/dist/libnet/ libnet] (CPAN: "install Net::Cmd")
 
 
* [http://search.cpan.org/dist/libwww-perl libwww-perl] (CPAN: "install Bundle::LWP")
 
* [http://search.cpan.org/dist/libwww-perl libwww-perl] (CPAN: "install Bundle::LWP")
 
** [http://search.cpan.org/dist/URI URI]
 
** [http://search.cpan.org/dist/URI URI]
 
** [http://search.cpan.org/dist/HTML-Tagset HTML::Tagset]
 
** [http://search.cpan.org/dist/HTML-Tagset HTML::Tagset]
 
** [http://search.cpan.org/dist/HTML-Parser HTML::Parser]
 
** [http://search.cpan.org/dist/HTML-Parser HTML::Parser]
* [http://search.cpan.org/dist/HTML-Mason HTML::Mason]
 
* [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 or [http://search.cpan.org/dist/DBD-mysql DBD::mysql] for MySQL)
 
** [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/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/DateManip Date::Manip]
* [http://search.cpan.org/dist/DateTime DateTime]
+
 
 +
==== Common modules ====
  
==== Modules of Indeterminate Popularity ====
+
These modules are included in many distributions.
 +
<!-- more nebulous criteria, but should be included in at least Debian, FreeBSD ports, have sigificant Perl mindshare -->
  
 
* [http://search.cpan.org/dist/Chart Chart] (CPAN: "install Chart::Base")
 
* [http://search.cpan.org/dist/Chart Chart] (CPAN: "install Chart::Base")
 
* [http://search.cpan.org/dist/Cache-Cache Cache::Cache]
 
* [http://search.cpan.org/dist/Cache-Cache Cache::Cache]
 +
* [http://search.cpan.org/dist/DateTime DateTime]
 +
* [http://search.cpan.org/dist/DateTime-Format-Strptime DateTime::Format::Strptime]
 +
* [http://search.cpan.org/dist/DateTime-Format-Natural DateTime-Format-Natural]
 +
* [http://search.cpan.org/dist/Email-Sender Email::Sender]
 +
* [http://search.cpan.org/dist/Email-Sender-Transport-SMTP-TLS Email::Sender::Transport::SMTP::TLS]
 +
* [http://search.cpan.org/dist/HTML-Mason HTML::Mason]
 +
* [http://search.cpan.org/dist/Locale-Codes Locale-Codes] (CPAN: "install Locale::Country")
 +
* [http://search.cpan.org/dist/Locale-SubCountry Locale::SubCountry]
 +
* [http://search.cpan.org/dist/MailTools MailTools] (CPAN: "install Mail::Internet")
 +
* [http://search.cpan.org/dist/MIME-tools MIME::Tools] (Note: do not use version 5.423)
 
* [http://search.cpan.org/dist/NetAddr-IP NetAddr::IP]
 
* [http://search.cpan.org/dist/NetAddr-IP NetAddr::IP]
 +
* [http://search.cpan.org/dist/Net-Ping Net::Ping]
 +
* [http://search.cpan.org/dist/Net-Ping-External Net::Ping::External]
 +
* [http://search.cpan.org/dist/Number-Format Number::Format]
 +
* [http://search.cpan.org/dist/Spreadsheet-WriteExcel Spreadsheet::WriteExcel]
 
* [http://search.cpan.org/dist/String-Approx String::Approx]
 
* [http://search.cpan.org/dist/String-Approx String::Approx]
* [http://search.cpan.org/dist/Locale-SubCountry Locale::SubCountry]
+
* [http://search.cpan.org/dist/Text-CSV_XS Text::CSV_XS]
* [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/Text-Template Text::Template]
* [http://search.cpan.org/dist/DateTime-Format-Strptime DateTime::Format::Strptime]
+
 
* [http://search.cpan.org/dist/Text-CSV_XS Text::CSV_XS]
+
==== Additional modules ====
* [http://search.cpan.org/dist/Spreadsheet-WriteExcel Spreadsheet::WriteExcel]
 
* [http://search.cpan.org/dist/Number-Format Number::Format]
 
  
==== Less common modules ====
+
<!-- our modules (DBIx::DBSchema, Net::SSH, H:W:SelectLayers, etc.) and other modules with questionable mindshare and distro pickup. -->
  
 +
* [http://search.cpan.org/dist/Authen-Passphrase Authen::Passphrase]
 
* [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/Business-US-USPS-WebTools Business::US::USPS::WebTools]
 +
* [http://search.cpan.org/dist/Color-Scheme Color::Scheme]
 +
* [http://search.cpan.org/dist/Crypt::PasswdMD5 Crypt::PasswdMD5]
 
* [http://search.cpan.org/dist/DBIx-DBSchema DBIx::DBSchema]
 
* [http://search.cpan.org/dist/DBIx-DBSchema DBIx::DBSchema]
* [http://search.cpan.org/dist/Tie-IxHash Tie::IxHash]
 
* [http://search.cpan.org/dist/Crypt::PasswdMD5 Crypt::PasswdMD5]
 
* [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/File-Slurp File::Slurp]
 +
* [http://search.cpan.org/dist/Frontier-RPC Frontier::RPC2]
 +
* [http://search.cpan.org/dist/HTML-Defang HTML::Defang]
 +
* [http://search.cpan.org/dist/HTML-Widgets-SelectLayers HTML::Widgets::SelectLayers]
 
* [http://search.cpan.org/dist/IPC-Run IPC::Run]
 
* [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/String-ShellQuote String::ShellQuote]
 
 
* [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/Color-Scheme Color::Scheme]
 
 
* [http://search.cpan.org/dist/Lingua-EN-NameParse Lingua::EN::NameParse]
 
* [http://search.cpan.org/dist/Lingua-EN-NameParse Lingua::EN::NameParse]
 
* [http://search.cpan.org/dist/Lingua-EN-Inflect Lingua::EN::Inflect]
 
* [http://search.cpan.org/dist/Lingua-EN-Inflect Lingua::EN::Inflect]
* [http://search.cpan.org/dist/Authen-Passphrase Authen::Passphrase]
 
 
* [http://search.cpan.org/dist/Net-Domain-TLD Net::Domain::TLD]
 
* [http://search.cpan.org/dist/Net-Domain-TLD Net::Domain::TLD]
* [http://search.cpan.org/dist/Business-US-USPS-WebTools Business::US::USPS::WebTools]
+
* [http://search.cpan.org/dist/Net-SSH Net::SSH]
 +
* [http://search.cpan.org/dist/Net-Whois-Raw Net::Whois::Raw]
 +
* [http://search.cpan.org/dist/String-ShellQuote String::ShellQuote]
 +
* [http://search.cpan.org/dist/Tie-IxHash Tie::IxHash]
 +
* [http://search.cpan.org/dist/Time-Duration Time::Duration]
  
 
==== Optional modules ====
 
==== Optional modules ====
Line 82: Line 95:
 
* [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)''
 +
 +
== Download Freeside ==
 +
* Get the source from one of the normal places
 +
**[http://www.freeside.biz/freeside/developers.html Open source link from the home page]
 +
**[http://www.freeside.biz/freeside/cvs.html Anonymous CVS]
 +
* Uncompress the tarball
  
 
== Installation ==
 
== Installation ==
  
 +
=== System User ===
 
* Add the user and group `freeside' to your system.
 
* Add the user and group `freeside' to your system.
 +
=== Database User ===
 
* Allow the freeside user full access to the freeside database.  
 
* Allow the freeside user full access to the freeside database.  
with PostgreSQL:
+
with Postgresql:
<pre>
 
$ 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
 
</pre>
 
or with Postgresql 8.3+:
 
 
<pre>
 
<pre>
 
[ as postgres/pgsql user ]
 
[ as postgres/pgsql user ]
Line 113: Line 124:
 
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';
 
</pre>
 
</pre>
 
+
=== Database Access ===
 
*Edit the top-level Makefile:  
 
*Edit the top-level Makefile:  
** Set DATASOURCE to your DBI data source, for example, <code>DBI:Pg:dbname=freeside</code> for PostgresSQL or <code>DBI:mysql:freeside</code> for MySQL. See the DBI manpage and the manpage for your DBD for the exact syntax of your DBI data source.  
+
** Configure the DATASOURCE to your DBI data source
** Set DB_PASSWORD to the freeside database user's password.  
+
*** 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.
  
 +
=== Database ===
 
* Add the freeside database to your database engine:  
 
* Add the freeside database to your database engine:  
 
with Postgres:  
 
with Postgres:  
Line 133: Line 147:
 
$ mysqladmin -u freeside -p create freeside  
 
$ mysqladmin -u freeside -p create freeside  
 
</pre>
 
</pre>
 
+
=== Perl Modules ===
 
* Build and install the Perl modules:  
 
* Build and install the Perl modules:  
 
<pre>
 
<pre>
Line 140: Line 154:
 
# make install-perl-modules
 
# make install-perl-modules
 
</pre>
 
</pre>
 
+
=== Basic configuration Files ===
 
* Create the necessary configuration files:
 
* Create the necessary configuration files:
 
<pre>
 
<pre>
Line 147: Line 161:
 
</pre>
 
</pre>
  
* 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.
+
=== Invoice Typesetting ===
 +
* If you are using typeset invoices, install fslongtable.sty:
 +
<pre>
 +
$ su
 +
# make install-texmf
 +
</pre>
 +
 
 +
=== Apache & Web GUI ===
 +
* Configuration
 +
** Enable mod_perl
 +
** 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
+
* To install the web interface, run:
 
<pre>
 
<pre>
 +
$ su
 
# make install-docs
 
# make install-docs
 
</pre>
 
</pre>
Line 160: Line 186:
 
* 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.)
 
* 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
+
* To install the apache configs, run:
 
<pre>
 
<pre>
 +
$ su
 
# make install-apache
 
# make install-apache
 
</pre>
 
</pre>
Line 167: Line 194:
 
''Note: Do not attempt to restart Apache (httpd) yet.''
 
''Note: Do not attempt to restart Apache (httpd) yet.''
  
 +
=== Initialize Data ===
 
* As the freeside UNIX user, run <code>freeside-setup -d your.domain.name</code> to create the database tables and initial data.
 
* As the freeside UNIX user, run <code>freeside-setup -d your.domain.name</code> to create the database tables and initial data.
 
<pre>
 
<pre>
Line 173: Line 201:
 
</pre>
 
</pre>
  
 +
=== Additional System Users ===
 
* Create the Freeside system users:  
 
* Create the Freeside system users:  
 
<pre>
 
<pre>
Line 181: Line 210:
 
</pre>
 
</pre>
  
 +
=== Create Freeside Users ===
 
* Create one or more Freeside users (your internal sales/tech folks, not customer accounts):
 
* Create one or more Freeside users (your internal sales/tech folks, not customer accounts):
 
<pre>
 
<pre>
Line 190: Line 220:
 
Additional users can be added using the same command or from the web interface.
 
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>)  
+
=== 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 <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>)
  
 +
=== RT ===
 
* Either [[Freeside:1.9:Documentation:RT_Installation|install the integrated RT ticketing system]], or delete the <code>ticket_system</code> entry from your conf table.
 
* Either [[Freeside:1.9:Documentation:RT_Installation|install the integrated RT ticketing system]], or delete the <code>ticket_system</code> entry from your conf table.
  
 +
<pre>
 +
su freeside
 +
psql freeside
 +
delete from conf where name = 'ticket_system';
 +
</pre>
 +
 +
=== Finalize ===
 
* Restart Apache (httpd) and log into the web interface using the username and password you entered above.
 
* Restart Apache (httpd) and log into the web interface using the username and password you entered above.
  
 
* Now proceed to the initial [[Freeside:1.9:Documentation:Administration|administration]] of your installation.
 
* Now proceed to the initial [[Freeside:1.9:Documentation:Administration|administration]] of your installation.

Latest revision as of 16:36, 19 December 2010

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
    • 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, 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.

Common modules

These modules are included in many distributions.

Additional modules

Optional modules

Download Freeside

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.

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

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.