Difference between revisions of "Freeside:1.7:Documentation:Installation"
From Freeside
m |
(all spammers must die) |
||
(64 intermediate revisions by 15 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. | + | * [http://www.perl.org/ Perl], minimum version 5.8.4 |
− | * [http://httpd.apache.org/ Apache], | + | * [http://httpd.apache.org/ Apache], SSL highly recommended) |
− | * [http://perl.apache.org/ mod_perl] | + | * [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, | + | ** [http://www.postgresql.org PostgreSQL] is recommended (v7.2 or later, v7.4 or later recommended). |
− | ** [http://www.mysql.com MySQL] is | + | ** [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 | + | ''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") | ||
Line 48: | Line 52: | ||
* [http://search.cpan.org/dist/DateManip Date::Manip] | * [http://search.cpan.org/dist/DateManip Date::Manip] | ||
* [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/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 | + | ==== 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 64: | Line 72: | ||
* [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/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] | ||
Line 72: | 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 78: | 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> | ||
$ su postgres (pgsql on some distributions) | $ su postgres (pgsql on some distributions) | ||
$ createuser -P freeside | $ createuser -P freeside | ||
Line 86: | 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 | ||
− | </ | + | </pre> |
− | + | 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'; | ||
− | + | </pre> | |
*Edit the top-level Makefile: | *Edit the top-level Makefile: | ||
Line 98: | Line 116: | ||
* Add the freeside database to your database engine: | * Add the freeside database to your database engine: | ||
− | + | with Postgres: | |
+ | <pre> | ||
$ su freeside | $ su freeside | ||
$ createdb -E sql_ascii freeside | $ createdb -E sql_ascii freeside | ||
− | </ | + | </pre> |
− | + | 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 | ||
− | + | </pre> | |
− | * Build and install the Perl modules: <pre | + | * Build and install the Perl modules: |
+ | <pre> | ||
$ make perl-modules | $ make perl-modules | ||
$ su | $ su | ||
# make install-perl-modules | # make install-perl-modules | ||
− | + | </pre> | |
− | * Create the necessary configuration files: <pre | + | * Create the necessary configuration files: |
+ | <pre> | ||
$ su | $ su | ||
# make create-config | # make create-config | ||
− | + | </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. |
* Edit the Makefile and set <code>FREESIDE_DOCUMENT_ROOT</code>. | * Edit the Makefile and set <code>FREESIDE_DOCUMENT_ROOT</code>. | ||
− | * Run < | + | * 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> | ||
+ | |||
+ | ''Note: Do not attempt to restart Apache (httpd) yet.'' | ||
+ | |||
+ | * As the freeside UNIX user, run <code>freeside-setup -d your.domain.name</code> to create the database tables and initial data. | ||
+ | <pre> | ||
$ su freeside | $ su freeside | ||
− | + | $ freeside-setup -d example.com | |
− | + | </pre> | |
− | |||
− | |||
− | |||
− | * | + | * Create the Freeside system users: |
+ | <pre> | ||
$ su freeside | $ su freeside | ||
− | $ freeside- | + | $ freeside-adduser -g 1 fs_queue |
− | + | $ freeside-adduser -g 1 fs_daily | |
+ | $ freeside-adduser -g 1 fs_selfservice | ||
+ | </pre> | ||
− | * Create | + | * Create one or more Freeside users (your internal sales/tech folks, not customer accounts): |
+ | <pre> | ||
$ su freeside | $ su freeside | ||
− | + | $ freeside-adduser -g 1 username | |
− | + | $ 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 14:52, 20 July 2009
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.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
- libnet (CPAN: "install Net::Cmd")
- libwww-perl (CPAN: "install Bundle::LWP")
- HTML::Mason
- Text::Template
- DBI
- DBD for your database engine (DBD::Pg for PostgreSQL or DBD::mysql for MySQL)
- 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)
- 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.)
- 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
- Text::CSV_XS
- Spreadsheet::WriteExcel
- Number::Format
Less common modules
- Business::CreditCard
- Net::Whois::Raw
- DBIx::DBSchema (Freeside v1.7.2: use DBIx::DBSchema v0.32, not later versions) (Freeside 1.7.3: use current DBIx::DBSchema)
- Tie::IxHash
- Crypt::PasswdMD5
- Time::Duration
- File::CounterFile
- IPC::Run
- IPC::Run3
- Net::SSH
- String::ShellQuote
- JSON
- HTML::Widgets::SelectLayers
- Color::Scheme
- 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 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 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 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 andQUEUED_USER
with the username of a Freeside user you created above, and runmake install-init
)
- Either install the integrated RT ticketing system, or delete the
ticket_system
file from your configuration directory (/usr/local/etc/freeside/conf.datasrc
).
- 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.