Difference between revisions of "Freeside:1.7:Documentation:Installation"
From Freeside
DronaCelac (talk | contribs) |
(all spammers must die) |
||
| Line 1: | Line 1: | ||
| − | |||
== Introduction == | == Introduction == | ||
Latest revision as of 13: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=freesidefor PostgresSQL orDBI:mysql:freesidefor 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_VERSIONto 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_CONFto 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.nameto 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_FILEwith the appropriate location on your system andQUEUED_USERwith the username of a Freeside user you created above, and runmake install-init)
- Either install the integrated RT ticketing system, or delete the
ticket_systemfile 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.
