Difference between revisions of "Freeside:2.3:Documentation:Installation"
From Freeside
(→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/ | + | <!-- 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/ | + | * [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-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/ | + | * [http://search.cpan.org/dist/Log-Dispatch Log::Dispatch] |
− | |||
* [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:: | + | * [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/ | + | * [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/ | + | * [http://search.cpan.org/dist/IO-Scalar IO::Scalar] |
− | * [http://search.cpan.org/dist/ | + | * [http://search.cpan.org/dist/IO-String IO::String] |
− | * [http://search.cpan.org/dist/ | + | * [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/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 | + | 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 | + | **[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.
- libwww-perl (CPAN: "install Bundle::LWP")
- DBI
- DBD for your database engine (DBD::Pg for PostgreSQL or DBD::mysql for MySQL)
- Date::Manip
- DateTime
- Frontier::RPC2
- GD::Barcode
- IPC::Run
- IPC::Run3
- JSON
- MailTools (CPAN: "install Mail::Internet")
- MIME::Tools (Note: do not use version 5.423)
- Net::SNMP
- SOAP::Lite
- TimeDate (CPAN: "install Date::Format")
- XML::LibXML
- XML::Simple
Common modules
These modules are included in many distributions.
- Chart (CPAN: "install Chart::Base")
- Cache::Cache
- DateTime::Format::Strptime
- DateTime-Format-Natural
- Email::Sender
- Email::Sender::Transport::SMTP::TLS
- Excel::Writer::XLSX
- HTML::Mason
- Locale-Codes (CPAN: "install Locale::Country")
- Locale::SubCountry
- Log::Dispatch
- NetAddr::IP
- Net::Ping
- Net::Ping::External
- Number::Format
- Spreadsheet::WriteExcel
- String::Approx
- Text::CSV_XS
- Term::ReadKey
- Text::Template
Additional modules
- Authen::Passphrase
- Business::CreditCard
- Business::US::USPS::WebTools
- CAM::PDF
- Color::Scheme
- Crypt::PasswdMD5
- Crypt::OpenSSL::RSA
- Date::Simple
- DateTime::Set
- DBIx::DBSchema
- File::CounterFile
- File::Slurp
- Geo::Coder::Googlev3
- Geo::GoogleEarth::Pluggable
- HTML::Defang
- HTML::ElementTable
- HTML::TableExtract
- HTML::Widgets::SelectLayers
- IO::Scalar
- IO::String
- IPC::Run::SafeHandles
- Lingua::EN::NameParse
- Lingua::EN::Inflect
- Net::Domain::TLD
- Net::OpenSSH
- Net::SSH
- Net::Whois::Raw
- String::ShellQuote
- Tie::IxHash
- Time::Duration
- XML::LibXML::LazyBuilder
Optional modules
- Apache::DBI (recommended for better web interface performance)
- Fax::Hylafax::Client (only if faxing invoices)
- POE (only if using alternate standalone XML-RPC server)
- Sys::SigAction (only if port combining with network monitoring)
Note on missing modules
Prerequisites missing from the documentation? Please add them (in the appropriate section).
Download Freeside
- Get the source from one of the normal places
- Uncompress the tarball
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.
- Configure the DATASOURCE to your DBI data source
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 andQUEUED_USER
with the username of a Freeside user you created above, and runmake install-init
)
RT
- Either install the integrated RT ticketing system, or delete the
ticket_system
entry from your conf table.
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.
- Now proceed to the initial administration of your installation.