Difference between revisions of "Freeside:1.7:Documentation:Installation"
(→Installation) |
(→Installation) |
||
| Line 151: | Line 151: | ||
</nowiki></pre> | </nowiki></pre> | ||
** Additional users: <pre><nowiki> | ** Additional users: <pre><nowiki> | ||
| − | $ su | + | $ su freeside |
# freeside-adduser -h /usr/local/etc/freeside/htpasswd username | # freeside-adduser -h /usr/local/etc/freeside/htpasswd username | ||
</nowiki></pre> | </nowiki></pre> | ||
| Line 157: | Line 157: | ||
* Create the Freeside system users: <pre><nowiki> | * Create the Freeside system users: <pre><nowiki> | ||
| − | $ su | + | $ su freeside |
# freeside-adduser fs_queue | # freeside-adduser fs_queue | ||
# freeside-adduser fs_daily | # freeside-adduser fs_daily | ||
Revision as of 10:37, 21 August 2006
Contents
Introduction
Install Freeside on a firewalled, private server, not a public (web, RADIUS, etc.) server.
Prerequisites
Packages
- Perl, minimum version 5.8.0 (5.8.3 for RT?)
- Apache, version 1.3 (mod_ssl highly recommended)
- mod_perl, version 1.29 (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")
Modules of Indeterminate Popularity
- Chart (CPAN: "install Chart::Base")
- Cache::Cache
- NetAddr::IP
- String::Approx
- Locale::SubCountry
- Frontier::RPC2
- Term::ReadKey
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
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=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 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
- Run a separate iteration of Apache[-SSL] with mod_perl enabled as the freeside user.
- Edit the Makefile and set
FREESIDE_DOCUMENT_ROOT.
- Run
make install-docs
- Configure Apache:
PerlModule HTML::Mason
- your freeside docuemnt root
<Directory /var/www/freeside> <Files ~ (\.cgi|\.html)> AddHandler perl-script .cgi .html PerlHandler HTML::Mason </Files> <Perl> require "/usr/local/etc/freeside/handler.pl"; </Perl> </Directory>
- Restrict access to this web interface - see the Apache documentation on user authentication. For example, to configure user authentication with mod_auth (flat files), add something like the following to your Apache httpd.conf file, adjusting for your actual paths:
- your freeside document root
<Directory /var/www/freeside> AuthName Freeside AuthType Basic AuthUserFile /usr/local/etc/freeside/htpasswd require valid-user </Directory>
- As the freeside UNIX user, run freeside-setup -d domain.name to create the database tables and initial data.
$ su freeside $ freeside-setup -d example.com
- Create one or more Freeside users (your internal sales/tech folks, not customer accounts). These users are setup using using Apache authentication, not UNIX user accounts. For example, using mod_auth (flat files):
- First user:
$ su
- freeside-adduser -c -h /usr/local/etc/freeside/htpasswd username
- Additional users:
$ su freeside
- freeside-adduser -h /usr/local/etc/freeside/htpasswd username
(using other auth types, add each user to your Apache authentication and then run: freeside-adduser username)
- Create the Freeside system users:
$ su freeside
- freeside-adduser fs_queue
- freeside-adduser fs_daily
- freeside-adduser fs_selfservice
- 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)
- Now proceed to the initial administration of your installation.
