Difference between revisions of "Freeside:1.7:Documentation:Installation"

From Freeside
Jump to: navigation, search
(Packages)
(Installation)
Line 127: Line 127:
 
* Run <code>make install-docs</code>
 
* Run <code>make install-docs</code>
  
* Configure Apache: <pre><nowiki>
+
* 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.)
PerlModule HTML::Mason
+
 
# your freeside docuemnt root
+
* Run <code>make install-apache</code>
<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>
 
</nowiki></pre>
 
 
* Restrict access to this web interface - see the [http://httpd.apache.org/docs/misc/FAQ.html#user-authentication Apache documentation on user authentication].  To allow the system to update passwords automatically, it is currently recommended to configure user authentication with [http://httpd.apache.org/docs/mod/mod_auth.html mod_auth] (flat files).  Add this to your Apache httpd.conf file: <pre><nowiki>
 
#your freeside document root
 
<Directory /var/www/freeside>
 
AuthName Freeside
 
AuthType Basic
 
AuthUserFile /usr/local/etc/freeside/htpasswd
 
require valid-user
 
</Directory>
 
</nowiki></pre>
 
  
 
* As the freeside UNIX user, run <code>freeside-setup -d your.domain.name</code> to create the database tables and initial data.<pre><nowiki>
 
* As the freeside UNIX user, run <code>freeside-setup -d your.domain.name</code> to create the database tables and initial data.<pre><nowiki>

Revision as of 16:52, 27 January 2007

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.3 (or minimum version 5.8.0 if the integrated RT is turned off)
  • 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

Modules of Indeterminate Popularity

Less common modules probably not included in anything but Debian?

Optional modules


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 or DBI: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.
  • 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

  1. make install-perl-modules
  • Create the necessary configuration files:

$ su

  1. 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
  • 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

  1. freeside-adduser -g 1 fs_queue
  2. freeside-adduser -g 1 fs_daily
  3. freeside-adduser -g 1 fs_selfservice
  • Create one or more Freeside users (your internal sales/tech folks, not customer accounts):

$ su freeside

  1. freeside-adduser -g 1 username
  2. 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 and QUEUED_USER with the username of a Freeside user you created above, and run make install-init)
  • Now proceed to the initial administration of your installation.