Difference between revisions of "Freeside:1.7:Documentation:Installation"
From Freeside
(→Less common modules probably not included in anything but Debian?) |
(fix <pre> sections) |
||
Line 82: | Line 82: | ||
* 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 | + | ** with PostgreSQL |
+ | <pre> | ||
$ su postgres (pgsql on some distributions) | $ su postgres (pgsql on some distributions) | ||
$ createuser -P freeside | $ createuser -P freeside | ||
Line 90: | Line 91: | ||
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 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 102: | Line 104: | ||
* Add the freeside database to your database engine: | * Add the freeside database to your database engine: | ||
− | ** with Postgres: <pre | + | ** with Postgres: |
+ | <pre> | ||
$ su freeside | $ su freeside | ||
$ createdb -E sql_ascii freeside | $ createdb -E sql_ascii 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. | * 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. | ||
Line 131: | Line 137: | ||
* Run <code>make install-apache</code> | * Run <code>make install-apache</code> | ||
− | * As the freeside UNIX user, run <code>freeside-setup -d your.domain.name</code> to create the database tables and initial data.<pre | + | * 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 | $ freeside-setup -d example.com | ||
− | + | </pre> | |
− | * Create the Freeside system users: <pre | + | * Create the Freeside system users: |
+ | <pre> | ||
$ su freeside | $ su freeside | ||
# freeside-adduser -g 1 fs_queue | # freeside-adduser -g 1 fs_queue | ||
# freeside-adduser -g 1 fs_daily | # freeside-adduser -g 1 fs_daily | ||
# freeside-adduser -g 1 fs_selfservice | # freeside-adduser -g 1 fs_selfservice | ||
− | + | </pre> | |
− | * Create one or more Freeside users (your internal sales/tech folks, not customer accounts):<pre | + | * Create one or more Freeside users (your internal sales/tech folks, not customer accounts): |
+ | <pre> | ||
$ su freeside | $ su freeside | ||
# freeside-adduser -g 1 username | # freeside-adduser -g 1 username | ||
# htpasswd /usr/local/etc/freeside/htpasswd username | # htpasswd /usr/local/etc/freeside/htpasswd username | ||
Password: | Password: | ||
− | + | </pre> | |
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. | ||
Revision as of 12:02, 13 April 2007
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, 7.4 or later recommended).
- MySQL is not currently supported. Developers intersted in maintaining MySQL support are welcome to ask on the -devel mailing list; most things work, but MySQL support needs a maintainer to update it for recent (and future) changes.
Note: the above only applies to the database used by the Freeside software itself. Freeside can integrate with RADIUS and other servers running MySQL or any other DBI-supported database.
- 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
- MailTools (CPAN: "install Mail::Internet")
- MIME::Tools
- 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
Less common modules probably not included in anything but Debian?
- Business::CreditCard
- Net::Whois::Raw
- DBIx::DBSchema
- Tie::IxHash
- Crypt::PasswdMD5
- Time::Duration
- File::CounterFile
- 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 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 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_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
- 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
).
- Now proceed to the initial administration of your installation.