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

From Freeside
Jump to: navigation, search
(Download Freeside)
(Log::Dispatch dep)
 
(13 intermediate revisions by 3 users not shown)
Line 24: Line 24:
  
 
These modules are included in most distributions.
 
These modules are included in most distributions.
<!-- reference: CentOS/RHEL 5, i.e. http://linux.mirrors.es.net/centos/5/os/x86_64/CentOS/  
+
<!-- reference: CentOS/RHEL 5, i.e. http://linux.mirrors.es.net/centos/6/os/x86_64/Packages/
 
  if its there, its everywhere... right? -->
 
  if its there, its everywhere... right? -->
  
Line 33: Line 33:
 
* [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/DateManip Date::Manip]
 +
* [http://search.cpan.org/dist/DateTime DateTime]
 +
* [http://search.cpan.org/dist/Frontier-RPC Frontier::RPC2]
 +
* [http://search.cpan.org/dist/GD-Barcode GD::Barcode]
 +
* [http://search.cpan.org/dist/IPC-Run IPC::Run]
 +
* [http://search.cpan.org/dist/IPC-Run3 IPC::Run3]
 +
* [http://search.cpan.org/dist/JSON JSON]
 +
* [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/Net-SNMP Net::SNMP]
 +
* [http://search.cpan.org/dist/SOAP-Lite SOAP::Lite]
 
* [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/DateManip Date::Manip]
+
* [http://search.cpan.org/dist/XML-LibXML XML::LibXML]
 +
* [http://search.cpan.org/dist/XML-Simple XML::Simple]
  
 
==== Common modules ====
 
==== Common modules ====
Line 43: Line 55:
 
* [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-Strptime DateTime::Format::Strptime]
 
* [http://search.cpan.org/dist/DateTime-Format-Natural DateTime-Format-Natural]
 
* [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 Email::Sender]
 
* [http://search.cpan.org/dist/Email-Sender-Transport-SMTP-TLS Email::Sender::Transport::SMTP::TLS]
 
* [http://search.cpan.org/dist/Email-Sender-Transport-SMTP-TLS Email::Sender::Transport::SMTP::TLS]
 +
* [http://search.cpan.org/dist/Excel-Writer-XLSX Excel::Writer::XLSX]
 
* [http://search.cpan.org/dist/HTML-Mason HTML::Mason]
 
* [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-Codes Locale-Codes] (CPAN: "install Locale::Country")
 
* [http://search.cpan.org/dist/Locale-SubCountry Locale::SubCountry]
 
* [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/Log-Dispatch Log::Dispatch]
* [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 Net::Ping]
Line 72: Line 83:
 
* [http://search.cpan.org/dist/CAM-PDF CAM::PDF]
 
* [http://search.cpan.org/dist/CAM-PDF CAM::PDF]
 
* [http://search.cpan.org/dist/Color-Scheme Color::Scheme]
 
* [http://search.cpan.org/dist/Color-Scheme Color::Scheme]
* [http://search.cpan.org/dist/Crypt::PasswdMD5 Crypt::PasswdMD5]
+
* [http://search.cpan.org/dist/Crypt-PasswdMD5 Crypt::PasswdMD5]
 +
* [http://search.cpan.org/dist/Crypt-OpenSSL-RSA Crypt::OpenSSL::RSA]
 +
* [http://search.cpan.org/dist/Date-Simple Date::Simple]
 +
* [http://search.cpan.org/dist/DateTime-Set DateTime::Set]
 
* [http://search.cpan.org/dist/DBIx-DBSchema DBIx::DBSchema]
 
* [http://search.cpan.org/dist/DBIx-DBSchema DBIx::DBSchema]
 
* [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/File-Slurp File::Slurp]
* [http://search.cpan.org/dist/Frontier-RPC Frontier::RPC2]
+
* [http://search.cpan.org/dist/Geo-Coder-Googlev3 Geo::Coder::Googlev3]
 +
* [http://search.cpan.org/dist/Geo-GoogleEarth-Pluggable Geo::GoogleEarth::Pluggable]
 
* [http://search.cpan.org/dist/HTML-Defang HTML::Defang]
 
* [http://search.cpan.org/dist/HTML-Defang HTML::Defang]
 +
* [http://search.cpan.org/dist/HTML-ElementTable HTML::ElementTable]
 +
* [http://search.cpan.org/dist/HTML-TableExtract HTML::TableExtract]
 
* [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/IPC-Run IPC::Run]
+
* [http://search.cpan.org/dist/IO-Scalar IO::Scalar]
* [http://search.cpan.org/dist/IPC-Run3 IPC::Run3]
+
* [http://search.cpan.org/dist/IO-String IO::String]
* [http://search.cpan.org/dist/JSON JSON]
+
* [http://search.cpan.org/dist/IPC-Run-SafeHandles IPC::Run::SafeHandles]
 
* [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/Net-Domain-TLD Net::Domain::TLD]
 
* [http://search.cpan.org/dist/Net-Domain-TLD Net::Domain::TLD]
 +
* [http://search.cpan.org/dist/Net-OpenSSH Net::OpenSSH]
 
* [http://search.cpan.org/dist/Net-SSH Net::SSH]
 
* [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/Net-Whois-Raw Net::Whois::Raw]
Line 90: Line 108:
 
* [http://search.cpan.org/dist/Tie-IxHash Tie::IxHash]
 
* [http://search.cpan.org/dist/Tie-IxHash Tie::IxHash]
 
* [http://search.cpan.org/dist/Time-Duration Time::Duration]
 
* [http://search.cpan.org/dist/Time-Duration Time::Duration]
 +
* [http://search.cpan.org/dist/XML-LibXML-LazyBuilder XML::LibXML::LazyBuilder]
  
 
==== Optional modules ====
 
==== Optional modules ====
  
* [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)''
 +
* [http://search.cpan.org/dist/Fax-Hylafax-Client Fax::Hylafax::Client] ''(only if faxing invoices)''
 +
* [http://search.cpan.org/dist/POE POE] ''(only if using alternate standalone XML-RPC server)''
 +
* [http://search.cpan.org/dist/Sys::SigAction Sys::SigAction] ''(only if port combining with network monitoring)''
  
 
==== Note on missing modules ====
 
==== Note on missing modules ====
  
Prerequisites missing from 2.1 documentation?  Please add them.
+
Prerequisites missing from the documentation?  Please add them (in the appropriate section).
  
 
== Download Freeside ==
 
== Download Freeside ==
 
* Get the source from one of the normal places  
 
* 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/developers.html Open source link from the home page]
**[http://www.freeside.biz/freeside/git.html Anonymous CVS]
+
**[http://www.freeside.biz/freeside/git.html Anonymous git]
 
* Uncompress the tarball
 
* Uncompress the tarball
  

Latest revision as of 15:41, 11 December 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.

Common modules

These modules are included in many distributions.

Additional modules

Optional modules

Note on missing modules

Prerequisites missing from the documentation? Please add them (in the appropriate section).

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 UTF8 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.