X-Git-Url: http://git.freeside.biz/gitweb/?p=freeside.git;a=blobdiff_plain;f=httemplate%2Fdocs%2Finstall.html;h=ed306f2d38b09ac5e83d33f5e803ad4c904970f8;hp=53eb8f8562bda37be791a81d92d7a4c4ee8fdcdd;hb=d384acea721092aebd4ffd972a2c3a80208e80ae;hpb=2e1ca65dcfcf6a8ef41a10e15e3d20200ffc871a diff --git a/httemplate/docs/install.html b/httemplate/docs/install.html index 53eb8f856..ed306f2d3 100644 --- a/httemplate/docs/install.html +++ b/httemplate/docs/install.html @@ -3,19 +3,28 @@

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. PostgreSQL is recommended. 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. -
Perl modules (CPAN will query, download and build perl modules automatically) +
Perl +
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 +
A transactional database engine supported by Perl's DBI.
- Array-PrintCols -
- Term-Query (make test broken; install manually) +
- PostgreSQL is recommended (v7or later). +
- MySQL MINIMUM VERSION 4.1 is untested but may work. Versions before 4.1 do not support standard SQL subqueries and are NOT SUPPORTED. If you are a developer who wishes to contribute MySQL 3.x/4.0 support, see ticket #438 in the bug-tracking system and ask on the -devel mailing list. + + MySQL's default MyISAM and ISAM table types are not supported. If you want to use MySQL, you must use one of the new transaction-safe table types such as BDB or InnoDB, and set it as the default table type using the --default-table-type=BDB or --default-table-type=InnoDB mysqld command-line option or by setting default-table-type=BDB or default-table-type=InnoDB in the my.cnf option file. +
+
Perl modules (CPAN will query, download and build perl modules automatically) +
- MIME-Base64
- Digest-MD5 +
- URI
- HTML-Tagset
- HTML-Parser @@ -24,7 +33,7 @@ Before installing, you need:
- Net-Whois
- libwww-perl
- Business-CreditCard -
- Data-ShowTable +
- MailTools
- TimeDate
- DateManip @@ -33,34 +42,70 @@ Before installing, you need:
- String-Approx
- Text-Template
- DBI -
- DBD for your database engine +
- DBD for your database engine (DBD::Pg for PostgreSQL, DBD::mysql for MySQL) +
- DBIx-DataSource
- DBIx-DBSchema
- Net-SSH
- String-ShellQuote
- Net-SCP
- Apache::ASP or HTML::Mason +
- Tie-IxHash +
- Time-Duration +
- HTML-Widgets-SelectLayers +
- Storable + +
- NetAddr-IP +
- Chart +
- 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 MySQL:

$ mysqladmin -u root password 'set_a_root_database_password'
+       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
+      
 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';
-      
 with PostgreSQL

Add the freeside database to your database engine. (with MySQL) (with PostgreSQL) -
Unpack the tarball:
```
gunzip -c fs-x.y.z.tar.gz | tar xvf -
```
-
Build and install the Perl libraries: + +
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: +

+$ su
+# make create-database

+ (or manually, with Postgres:) +

+$ su freeside
+$ createdb freeside

+ (with MySQL:) +

+$ mysqladmin -u freeside -p create freeside

Build and install the Perl modules:

-$ cd FS/
-$ perl Makefile.PL
-$ make
+$ make perl-modules
 $ su
-# make install UNINST=1

You should run a separate iteration of Apache[-SSL] with mod_perl enabled as the freeside user. +# 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.

@@ -69,38 +114,56 @@ $ su

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

Copy aspdocs/ to your web server's document space: +

+cp aspdocs /usr/local/apache/htdocs/freeside-asp
+

Create a Global directory, such as /usr/local/etc/freeside/asp-global/: +

+mkdir /usr/local/etc/freeside/asp-global/
+chown freeside /usr/local/etc/freeside/asp-global/
+

Copy htetc/global.asa to the Global directory: +

+cp htetc/global.asa /usr/local/etc/freeside/asp-global/global.asa
+

Configure Apache for the Global directory and to execute .cgi files using Apache::ASP. For example:

-<Directory /usr/local/apache/htdocs/freeside-asp>
-<Files ~ (\.cgi)>
-AddHandler perl-script .cgi
+PerlModule Apache::ASP
+<Directory /usr/local/apache/htdocs/freeside-asp>
+<Files ~ (\.cgi|\.html)>
+SetHandler perl-script
 PerlHandler Apache::ASP
 </Files>
 <Perl>
 $MLDBM::RemoveTaint = 1;
 </Perl>
-PerlSetVar Global /usr/local/etc/freeside/asp-global/
+PerlSetVar Global /usr/local/etc/freeside/asp-global/
+PerlSetVar Debug 2
+PerlSetVar RequestBinaryRead Off
 </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 +
Copy masondocs/ to your web server's document space. (For example: /usr/local/apache/htdocs/freeside-mason) +
Copy htetc/handler.pl to /usr/local/etc/freeside +
Edit handler.pl and: +
- set an appropriate comp_root, such as /usr/local/apache/htdocs/freeside-mason +
- set an appropriate data_dir, such as /usr/local/etc/freeside/masondata +
+

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
+<Directory /usr/local/apache/htdocs/freeside-mason>
+<Files ~ (\.cgi|.html)>
+SetHandler perl-script
 PerlHandler HTML::Mason
 </Files>
 <Perl>
-require "/usr/local/apache/conf/handler.pl";
+require "/usr/local/etc/freeside/handler.pl";
 </Perl>
 </Directory>

@@ -108,13 +171,38 @@ require "/usr/local/apache/conf/handler.pl";

Restrict access to this web interface. (with Apache) -
Create the necessary configuration files. -
Create the `/usr/local/etc/freeside/counters.datasrc', - `/usr/local/etc/freeside/cache.datasrc', and - `/usr/local/etc/freeside/export.datasrc' directories for each datasrc (owned by the freeside user). -
As the freeside user, run bin/fs-setup to create the database tables. -
freeside-queued was installed with the Perl modules. Start it now and ensure that is run upon system startup. +
Restrict access to this web interface - see the Apache documentation on user authentication. For example, to configure user authentication with mod_auth (flat files): +
```
+<Directory /usr/local/apache/htdocs/freeside-asp>
+AuthName Freeside
+AuthType Basic
+AuthUserFile /usr/local/etc/freeside/htpasswd
+require valid-user
+</Directory>
+
```
+
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-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 freeside-setup username to create the database tables, passing the username of a Freeside user you created above: +
```
+$ su freeside
+$ freeside-setup username
+
```
+ Alternately, use the -s option to enable shipping addresses: freeside-setup -s username +
As the freeside UNIX user, run bin/populate-msgcat username (in the untar'ed freeside directory) to populate the message catalog, passing the username of a Freeside user you created above: +
```
+$ su freeside
+$ cd /path/to/freeside/
+$ bin/populate-msgcat username
+
```
+
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.