doc updates
[freeside.git] / htdocs / docs / install.html
1 <head>
2   <title>Installation</title>
3 </head>
4 <body>
5 <h1>Installation</h1>
6 Before installing, you need:
7 <ul>
8   <li>A web server, such as <a href="">Apache-SSL</a> or <a href="">Apache</a>
9   <li><a href="">SSH</a>
10   <li><a href="">Perl</a> (at least 5.004_05 for the 5.004 series or 5.005_03 for the 5.005 series.  Don't enable experimental features like threads or the PerlIO abstraction layer.)
11   <li>A database engine supported by Perl's <a href="">DBI</a>, such as <a href="">MySQL</a> or <a href="">PostgreSQL</a> (verstion 6.5 or higher) (see the <a href="postgresql.html">PostgreSQL notes</a>)
12   <li>Perl modules (<a href="">CPAN</a> will query, download and build perl modules automatically)
13     <ul>
14       <li><a href="">Array-PrintCols</a>
15       <li><a href="">Term-Query</a> (make test broken; install manually)
16       <li><a href="">MIME-Base64</a>
17       <li><a href="">Data-Dumper</a>
18       <li><a href="">Digest-MD5</a>
19       <li><a href="">URI</a>
20       <li><a href="">HTML-Parser</a>
21       <li><a href="">libnet</a>
22       <li><a href="">Locale-Codes</a>
23       <li><a href="">Net-Whois</a>
24       <li><a href="">libwww-perl</a>
25       <li><a href="">Business-CreditCard</a>
26       <li><a href="">Data-ShowTable</a>
27       <li><a href="">MailTools</a>
28       <li><a href="">TimeDate</a>
29       <li><a href="">DateManip</a>
30       <li><a href="">File-CounterFile</a>
31       <li><a href="">FreezeThaw</a>
32       <li><a href="">String-Approx</a>
33       <li><a href="">Text-Template</a>
34       <li><a href="">DBI
35       <li><a href="">DBD for your database engine</a>
36     </ul>
37 </ul>
38 Install the Freeside distribution:
39 <ul>
40   <li>Add the user `freeside' to your system.
41   <li>Add the freeside database to your database engine.  (with <a href="">MySQL</a>) (with <a href="">PostgreSQL</a>)
42   <li>Allow the freeside user full access to the freeside database.
43     <ul>
44       <li> with <a href="">MySQL</a>:<pre>$ mysqladmin -u root password '<i>set_a_root_database_password</i>'
45 $ mysql -u root -p
46 mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,DROP on freeside.* TO freeside@localhost IDENTIFIED BY '<i>set_a_freeside_database_password</i>';</pre>
47       <li> with <a href="">PostgreSQL</a>
48     </ul>
49   <li>Unpack the tarball: <pre>gunzip -c fs-x.y.z.tar.gz | tar xvf -</pre>
50   <li>Build and install the Perl libraries:
51     <pre>
52 $ cd FS/
53 $ perl Makefile.PL
54 $ make
55 $ su
56 # make install</pre>
57   <li>Copy or link fs-x.y.z/htdocs to your web server's document space.  <pre>mkdir /usr/local/apache/htdocs/freeside
58 cp -r fs-x.y.z/htdocs/* /usr/local/apache/htdocs/freeside</pre> or <pre>ln -s /full/path/to/fs-x.y.z/htdocs /usr/local/apache/htdocs/freeside</pre>
59   <li>Restrict access to this web interface.  (with <a href="">Apache</a>)
60   <li>Enable CGI execution for files with the `.cgi' extension.  (with <a href="">Apache</a>)
61   <li>Set ownership and permissions for the web interface.  The web interface needs to run as the freeside user - there are several ways to do this.
62     <ul>
63       <li>Use Perl's setuid emulation: see the <a href="">Security Bugs</a> section of the <a href="">perlsec</a> manpage.
64 <pre>cd /usr/local/apache/htdocs/freeside
65 chown -R freeside .
66 chmod 4755 browse/*.cgi edit/*.cgi edit/process/*.cgi misc/*.cgi misc/process/*.cgi search/*.cgi view/*.cgi</pre>
67       <li>Use Apache's <a href="">suEXEC</a>.
68 <pre>cd /usr/local/apache/htdocs/freeside
69 chown -R freeside .
70 chmod 755 browse/*.cgi edit/*.cgi edit/process/*.cgi misc/*.cgi misc/process/*.cgi search/*.cgi view/*.cgi</pre>
71       <li>Use <a href="">mod_perl</a>.  You should run a separate iteration of Apache[-SSL] as the freeside user.  (Warning:  The redirect method of 2.36 [as distributed with Perl 5.004_04] is broken under mod_perl.  Downlaod the current version from <a href="">CPAN</a>.  Apache 1.3.6 is also highly recommended because of signal handling problems in earlier versions.)
72 <pre>cd /usr/local/apache/htdocs/freeside
73 chown -R root .
74 chmod 755 browse/*.cgi edit/*.cgi edit/process/*.cgi misc/*.cgi misc/process/*.cgi search/*.cgi view/*.cgi</pre>
75     </ul>
76 <li>Create the necessary <a href="config.html">configuration files</a>.
77 <li>Create the `/usr/local/etc/freeside/counters.<i>datasrc</i>', and 
78   `/usr/local/etc/freeside/export.<i>datasrc</i>' directories for each <i>datasrc</i> (owned by the freeside user).
79   <li>As the freeside user, run bin/fs-setup to create the database tables.
80 </ul>
81 </body>