httemplate/docs/install.html


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

<head>
  <title>Installation</title>
</head>
<body>
<h1>Installation</h1>
Before installing, you need:
<ul>
  <li>A web server, such as <a href="http://www.apache-ssl.org">Apache-SSL</a> or <a href="http://www.apache.org">Apache</a>
  <li><a href="http://perl.apache.org/">mod_perl</a>
  <li><a href="http://www.openssh.com//">SSH</a> (<a href="http://www.openssh.com//">OpenSSH</a> is recommended.  SSH Communications Security <a href="http://www.ssh.com/products/ssh/download.cfm">commercial SSH version 3</a> has been reported incompatible with Freeside.)
  <li><a href="http://www.perl.com/">Perl</a>  Don't enable experimental features like threads or the PerlIO abstraction layer.
  <li>A <b>transactional</b> database engine supported by Perl's <a href="http://www.hermetica.com/technologia/DBI/">DBI</a>.
    <ul>
      <li><a href="http://www.postgresql.org/">PostgreSQL</a> is recommended.
      <li>MySQL has been reported to work.  <b>MySQL's default <a href="http://www.mysql.com/doc/M/y/MyISAM.html">MyISAM</a> and <a href="http://www.mysql.com/doc/I/S/ISAM.html">ISAM</a> table types are not supported</b>.  If you really want to use MySQL, you need to use one of the new <a href="http://www.mysql.com/doc/T/a/Table_types.html">transaction-safe table types</a> such as <a href="http://www.mysql.com/doc/B/D/BDB.html">BDB</a>, and set it as the default table type using the <code>--default-table-type=BDB</code> <a href="http://www.mysql.com/documentation/mysql/bychapter/manual_MySQL_Database_Administration.html#Command-line_options">mysqld command-line option</a> or by setting <code>default-table-type=BDB</code> in the <a href="http://www.mysql.com/documentation/mysql/bychapter/manual_MySQL_Database_Administration.html#Option_files">my.cnf option file</a>.
    </ul>
  <li>Perl modules (<a href="http://theoryx5.uwinnipeg.ca/CPAN/perl/CPAN.html">CPAN</a> will query, download and build perl modules automatically)
    <ul>
      <li><a href="http://search.cpan.org/search?dist=Array-PrintCols">Array-PrintCols</a>
      <li><a href="http://search.cpan.org/search?dist=Term-Query">Term-Query</a> (make test broken; install manually)
      <li><a href="http://search.cpan.org/search?dist=MIME-Base64">MIME-Base64</a>
      <li><a href="http://search.cpan.org/search?dist=Digest-MD5">Digest-MD5</a>
      <li><a href="http://search.cpan.org/search?dist=URI">URI</a>
      <li><a href="http://search.cpan.org/search?dist=HTML-Tagset">HTML-Tagset</a>
      <li><a href="http://search.cpan.org/search?dist=HTML-Parser">HTML-Parser</a>
      <li><a href="http://search.cpan.org/search?dist=libnet">libnet</a>
      <li><a href="http://search.cpan.org/search?dist=Locale-Codes">Locale-Codes</a>
      <li><a href="http://search.cpan.org/search?dist=Net-Whois">Net-Whois</a>
      <li><a href="http://search.cpan.org/search?dist=libwww-perl">libwww-perl</a>
      <li><a href="http://search.cpan.org/search?dist=Business-CreditCard">Business-CreditCard</a>
      <li><a href="http://search.cpan.org/search?dist=Data-ShowTable">Data-ShowTable</a>
      <li><a href="http://search.cpan.org/search?dist=MailTools">MailTools</a>
      <li><a href="http://search.cpan.org/search?dist=TimeDate">TimeDate</a>
      <li><a href="http://search.cpan.org/search?dist=DateManip">DateManip</a>
      <li><a href="http://search.cpan.org/search?dist=File-CounterFile">File-CounterFile</a>
      <li><a href="http://search.cpan.org/search?dist=FreezeThaw">FreezeThaw</a>
      <li><a href="http://search.cpan.org/search?dist=String-Approx">String-Approx</a>
      <li><a href="http://search.cpan.org/search?dist=Text-Template">Text-Template</a>
      <li><a href="http://search.cpan.org/search?dist=DBI">DBI</a>
      <li><a href="http://search.cpan.org/search?mode=module&query=DBD">DBD for your database engine</a>
      <li><a href="http://search.cpan.org/search?dist=DBIx-DataSource">DBIx-DataSource</a>
      <li><a href="http://search.cpan.org/search?dist=DBIx-DBSchema">DBIx-DBSchema</a>
      <li><a href="http://search.cpan.org/search?dist=Net-SSH">Net-SSH</a>
      <li><a href="http://search.cpan.org/search?dist=String-ShellQuote">String-ShellQuote</a>
      <li><a href="http://search.cpan.org/search?dist=Net-SCP">Net-SCP</a>
      <li><a href="http://www.apache-asp.org/">Apache::ASP</a> or <a href="http://www.masonhq.com/">HTML::Mason</a>
    </ul>
</ul>
Install the Freeside distribution:
<ul>
  <li>Add the user `freeside' to your system.
  <li>Allow the freeside user full access to the freeside database.
    <ul>
      <li> with <a href="http://www.mysql.com/documentation/mysql/bychapter/manual_MySQL_Database_Administration.html#User_Account_Management">MySQL</a>:<pre>$ mysqladmin -u root password '<i>set_a_root_database_password</i>'
$ mysql -u root -p
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>
      <li> with <a href="http://www.postgresql.org/users-lounge/docs/7.1/postgres/user-manag.html#DATABASE-USERS">PostgreSQL</a>
    </ul>
  <li>Add the freeside database to your database engine.  (with <a href="http://www.mysql.com/documentation/mysql/bychapter/manual_Reference.html#CREATE_DATABASE">MySQL</a>) (with <a href="http://www.postgresql.org/users-lounge/docs/7.1/postgres/managing-databases.html#MANAGE-AG-CREATEDB">PostgreSQL</a>)
  <li>Unpack the tarball: <pre>gunzip -c fs-x.y.z.tar.gz | tar xvf -</pre>
  <li>Build and install the Perl libraries:
    <pre>
$ cd FS/
$ perl Makefile.PL
$ make
$ su
# make install UNINST=1</pre>
    <li>You should run a separate iteration of Apache[-SSL] with mod_perl enabled as the freeside user.
</ul>
<table>
  <tr>
    <th>Apache::ASP</th><th>Mason</th>
  </tr>
  <tr>
    <td><ul>
      <li>Run <tt>make aspdocs</tt>
      <li>Copy <tt>aspdocs/</tt> to your web server's document space.
      <li>Create a <a href="http://www.apache-asp.org/config.html#Global">Global</a> directory, such as <tt>/usr/local/etc/freeside/asp-global/</tt>
      <li>Copy <tt>htetc/global.asa</tt> to the Global directory.
      <li>Configure Apache for the Global directory and to execute .cgi files using Apache::ASP.  For example:
<font size="-1"><pre>
&lt;Directory /usr/local/apache/htdocs/freeside-asp&gt;
&lt;Files ~ (\.cgi)&gt;
AddHandler perl-script .cgi
PerlHandler Apache::ASP
&lt;/Files&gt;
&lt;Perl&gt;
$MLDBM::RemoveTaint = 1;
&lt;/Perl&gt;
PerlSetVar Global /usr/local/etc/freeside/asp-global/
&lt;/Directory&gt;
</pre></font>
    </ul></td>
    <td><ul>
      <li>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.
      <li>Run <tt>make masondocs</tt>
      <li>Copy <tt>masondocs/</tt> to your web server's document space.
      <li>Copy <tt>htetc/handler.pl</tt> to your web server's configuration directory.
      <li>Edit <tt>handler.pl</tt> and set an appropriate <tt>data_dir</tt>, such as <tt>/usr/local/etc/freeside/mason-data</tt>
      <li>Configure Apache to use the <tt>handler.pl</tt> file and to execute .cgi files using HTML::Mason.  For example:
<font size="-1"><pre>
&lt;Directory /usr/local/apache/htdocs/freeside-mason&gt;
&lt;Files ~ (\.cgi)&gt;
AddHandler perl-script .cgi
PerlHandler HTML::Mason
&lt;/Files&gt;
&lt;Perl&gt;
require "/usr/local/apache/conf/handler.pl";
&lt;/Perl&gt;
&lt;/Directory&gt;
</pre></font>
    </ul></td>
  </tr>
</table>
<ul>
<li>Restrict access to this web interface.  (with <a href="http://httpd.apache.org/docs/misc/FAQ.html#user-authentication">Apache</a>).    For example, to configure user authentication with flat files:
<font size="-1"><pre>
&lt;Directory /usr/local/apache/htdocs/freeside-asp&gt;
PerlSetVar Global /usr/local/etc/freeside/asp-global/
AuthName Freeside
AuthType Basic
AuthUserFile /usr/local/etc/apache/htpasswd
require valid-user
&lt;/Directory&gt;
</pre>
<li>Create the necessary <a href="config.html">configuration files</a>.
<li>Create the `/usr/local/etc/freeside/counters.<i>datasrc</i>', 
  `/usr/local/etc/freeside/cache.<i>datasrc</i>', and 
  `/usr/local/etc/freeside/export.<i>datasrc</i>' directories for each <i>datasrc</i> (owned by the freeside user).
  <li>As the freeside user, run bin/fs-setup to create the database tables.
  <li>freeside-queued was installed with the Perl modules.  Start it now and ensure that is run upon system startup.
  <li>Now proceed to the initial <a href="admin.html">administration</a> of your installation.
</ul>
</body>