X-Git-Url: http://git.freeside.biz/gitweb/?a=blobdiff_plain;f=httemplate%2Fdocs%2Finstall.html;h=78172e8e47bd52accab486a6a011b89b80c05f24;hb=c509ea790c3d0631a0e1f79527ec937e419e380e;hp=60f549edb25d93b670e97ac231c859191760b6dd;hpb=70fa760135ca13a320a627d01e139f9ddb4d8689;p=freeside.git diff --git a/httemplate/docs/install.html b/httemplate/docs/install.html index 60f549edb..78172e8e4 100644 --- a/httemplate/docs/install.html +++ b/httemplate/docs/install.html @@ -3,74 +3,115 @@

Installation

+Note: Install Freeside on a firewalled, private server, not a public (web, RADIUS, etc.) server.

Before installing, you need:

A web server, such as Apache-SSL or Apache -
mod_perl -
SSH (OpenSSH is recommended. SSH Communications Security commercial SSH version 3 has been reported incompatible with Freeside.) -
Perl Don't enable experimental features like threads or the PerlIO abstraction layer. -
A transactional database engine supported by Perl's DBI. +
Perl, minimum version 5.005_03. (5.8.3 for the integrated RT ticketing) +
Apache (mod_ssl or Apache-SSL highly recommended) +
mod_perl (if compiling your own mod_perl, make sure you set the EVERYTHING=1 compile-time option) +
SSH (OpenSSH is recommended. SSH Communications Security commercial SSH version 3 has been reported incompatible with Freeside.) +
rsync +
Optional, enables typeset invoices: teTeX and Ghostscript (included with most distributions). +
A transactional database engine supported by Perl's DBI.
- PostgreSQL (v7 or higher) is recommended. -
- MySQL has been reported to work. MySQL's default MyISAM and ISAM table types are not supported. If you really want to use MySQL, you need to use one of the new transaction-safe table types such as BDB, and set it as the default table type using the --default-table-type=BDB mysqld command-line option or by setting default-table-type=BDB in the my.cnf option file. +
- 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; many things work, but MySQL support needs a maintainer to update it for recent (and future) changes. +
-
Perl modules (CPAN will query, download and build perl modules automatically) + 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. +
Perl modules (CPAN will query, download and build perl modules automatically)
- Array-PrintCols -
- Term-Query (make test broken; install manually) -
- MIME-Base64 -
- Digest-MD5 -
- URI -
- HTML-Tagset -
- HTML-Parser -
- libnet -
- Locale-Codes -
- Net-Whois -
- libwww-perl -
- Business-CreditCard -
- Data-ShowTable -
- MailTools -
- TimeDate -
- DateManip -
- File-CounterFile -
- FreezeThaw -
- String-Approx -
- Text-Template -
- DBI -
- DBD for your database engine -
- DBIx-DataSource -
- DBIx-DBSchema -
- Net-SSH -
- String-ShellQuote -
- Net-SCP -
- Apache::ASP or HTML::Mason + +
- MIME-Base64 +
- Digest-MD5 + +
- URI +
- HTML-Tagset +
- HTML-Parser +
- libnet +
- Locale-Codes +
- Net-Whois-Raw +
- libwww-perl +
- Business-CreditCard + +
- MailTools +
- TimeDate +
- DateManip +
- File-CounterFile +
- FreezeThaw +
- String-Approx +
- Text-Template +
- DBI +
- DBD for your database engine (DBD::Pg for PostgreSQL) + +
- DBIx-DBSchema +
- Net-SSH +
- String-ShellQuote +
- Net-SCP +
- HTML::Mason +
- Tie-IxHash +
- Time-Duration +
- HTML-Widgets-SelectLayers +
- Storable +
- Cache::Cache +
- NetAddr-IP +
- Chart +
- Crypt::PasswdMD5 +
- Locale::SubCountry +
- Frontier::RPC +
- Text::CSV_XS +
- Spreadsheet::WriteExcel +
- IO-stringy (IO::Scalar) +
- Frontier::RPC (Frontier::RPC2) +
- MIME::Entity (MIME-tools) +
- IPC::Run3 +
- Term::ReadKey + +
- JSON +
- Fax::Hylafax::Client (Required if using FAX invoice destinations) +
- Apache::DBI (optional but recommended for better webinterface performance)

Install the Freeside distribution:

Add the user `freeside' to your system. +
Add the user and group `freeside' to your system.
Allow the freeside user full access to the freeside database.
- with PostgreSQL:
```
-$ su postgres
-$ createuser -P freeside
```
  +$ 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
- 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';
```
-
Unpack the tarball:
```
gunzip -c fs-x.y.z.tar.gz | tar xvf -
```
+
Edit the top-level Makefile:
- Set DATASOURCE to your DBI data source, for example, DBI:Pg:host=localhost;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 a DBI data source. -
- Set DB_ADMIN_PASSWORD to the freeside database user's password. +
- 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: -

-$ su
-# make create-database

with Postgres: +

+$ su freeside
+$ createdb -E sql_ascii freeside

with MySQL: +

+$ mysqladmin -u freeside -p create freeside

Build and install the Perl modules:

 $ make perl-modules
@@ -80,58 +121,27 @@ $ su
 $ su
 # make create-config

You should run a separate iteration of Apache[-SSL] with mod_perl enabled as the freeside user. -

- - - - - - - - -

Apache::ASP Mason

Apache::ASP	Mason
- Run `make aspdocs` - Copy `aspdocs/` to your web server's document space. - Create a Global directory, such as `/usr/local/etc/freeside/asp-global/` - Copy `htetc/global.asa` to the Global directory. - Configure Apache for the Global directory and to execute .cgi files using Apache::ASP. For example: + Run a separate iteration of Apache[-SSL] with mod_perl enabled as the freeside user. + Edit the `Makefile` and set `TEMPLATE` to `asp` or `mason`. Also set `FREESIDE_DOCUMENT_ROOT`. + Run `make install-docs`. + Configure Apache: -<Directory /usr/local/apache/htdocs/freeside-asp> -<Files ~ (\.cgi)> -AddHandler perl-script .cgi -PerlHandler Apache::ASP -</Files> -<Perl> -$MLDBM::RemoveTaint = 1; -</Perl> -PerlSetVar Global /usr/local/etc/freeside/asp-global/ -</Directory> - -	- NOTE: Mason support is still a bit buggy in the 1.4.0 prereleases. This will be fixed before 1.4.0. You have been warned. - Run `make masondocs` - Copy `masondocs/` to your web server's document space. - Copy `htetc/handler.pl` to your web server's configuration directory. - Edit `handler.pl` and set an appropriate `data_dir`, such as `/usr/local/etc/freeside/mason-data` - Configure Apache to use the `handler.pl` file and to execute .cgi files using HTML::Mason. For example: - -<Directory /usr/local/apache/htdocs/freeside-mason> -<Files ~ (\.cgi)> -AddHandler perl-script .cgi +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/apache/conf/handler.pl"; +require "/usr/local/etc/freeside/handler.pl"; </Perl> </Directory> -

Run make aspdocs -
Copy aspdocs/ to your web server's document space. -
Create a Global directory, such as /usr/local/etc/freeside/asp-global/ -
Copy htetc/global.asa to the Global directory. -
Configure Apache for the Global directory and to execute .cgi files using Apache::ASP. For example: +
Run a separate iteration of Apache[-SSL] with mod_perl enabled as the freeside user. +
Edit the Makefile and set TEMPLATE to asp or mason. Also set FREESIDE_DOCUMENT_ROOT. +
Run make install-docs. +

Configure Apache:

-<Directory /usr/local/apache/htdocs/freeside-asp>
-<Files ~ (\.cgi)>
-AddHandler perl-script .cgi
-PerlHandler Apache::ASP
-</Files>
-<Perl>
-$MLDBM::RemoveTaint = 1;
-</Perl>
-PerlSetVar Global /usr/local/etc/freeside/asp-global/
-</Directory>
-

NOTE: Mason support is still a bit buggy in the 1.4.0 prereleases. This will be fixed before 1.4.0. You have been warned. -
Run make masondocs -
Copy masondocs/ to your web server's document space. -
Copy htetc/handler.pl to your web server's configuration directory. -
Edit handler.pl and set an appropriate data_dir, such as /usr/local/etc/freeside/mason-data -

Configure Apache to use the handler.pl file and to execute .cgi files using HTML::Mason. For example: -

-<Directory /usr/local/apache/htdocs/freeside-mason>
-<Files ~ (\.cgi)>
-AddHandler perl-script .cgi
+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/apache/conf/handler.pl";
+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): +

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:

-<Directory /usr/local/apache/htdocs/freeside-asp>
-PerlSetVar Global /usr/local/etc/freeside/asp-global/
+#your freeside document root
+<Directory /var/www/freeside>
 AuthName Freeside
 AuthType Basic
 AuthUserFile /usr/local/etc/freeside/htpasswd
@@ -142,18 +152,22 @@ require valid-user
     
       First user:
 $ su
-$ freeside-adduser -c -h /usr/local/etc/freeside/htpasswd username
+# freeside-adduser -c -h /usr/local/etc/freeside/htpasswd username

Additional users:
```
$ su
-$ freeside-adduser -h /usr/local/etc/freeside/htpasswd username
```
+# 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 -

As the freeside UNIX user, run bin/fs-setup username to create the database tables, passing the username of a Freeside user you created above: + (using other auth types, add each user to your Apache authentication and then run: freeside-adduser username) +

Create the Freeside system users: +

$ su
+# freeside-adduser fs_queue
+# freeside-adduser fs_selfservice

As the freeside UNIX user, run freeside-setup -d domain.name username to create the database tables and initial data, passing the username of a Freeside user you created above:

 $ su freeside
-$ bin/fs-setup username
+$ freeside-setup -d example.com username

freeside-queued was installed with the Perl modules. Start it now and ensure that is run upon system startup. +

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 systemand 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.