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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
<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> (v7 or higher) 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.postgresql.org/users-lounge/docs/7.1/postgres/user-manag.html#DATABASE-USERS">PostgreSQL</a>:
<pre>
$ su postgres
$ createuser -P freeside</pre>
<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>
</ul>
<li>Unpack the tarball: <pre>gunzip -c fs-x.y.z.tar.gz | tar xvf -</pre>
<li>Edit the top-level Makefile:
<ul>
<li>Set <tt>DATASOURCE</tt> to your <a href="http://search.cpan.org/doc/TIMB/DBI-1.20/DBI.pm">DBI data source</a>, for example, <tt>DBI:Pg:host=localhost;dbname=freeside</tt> for PostgresSQL or <tt>DBI:mysql:freeside</tt> for MySQL. See the <a href="http://search.cpan.org/doc/TIMB/DBI-1.20/DBI.pm">DBI manpage</a> and the <a href="http://search.cpan.org/search?mode=module&query=DBD">manpage for your DBD</a> for the exact syntax of a DBI data source.
<li>Set <tt>DB_ADMIN_PASSWORD</tt> to the freeside database user's password.
</ul>
<li>Add the freeside database to your database engine:
<pre>
$ su
# make create-database</pre>
<li>Build and install the Perl modules:
<pre>
$ make perl-modules
$ su
# make install-perl-modules</pre>
<li>Create the necessary configuration files:<pre>
$ su
# make create-config
</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>
<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>
</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>
<Directory /usr/local/apache/htdocs/freeside-mason>
<Files ~ (\.cgi)>
AddHandler perl-script .cgi
PerlHandler HTML::Mason
</Files>
<Perl>
require "/usr/local/apache/conf/handler.pl";
</Perl>
</Directory>
</pre></font>
</ul></td>
</tr>
</table>
<ul>
<li>Restrict access to this web interface - see the <a href="http://httpd.apache.org/docs/misc/FAQ.html#user-authentication">Apache documentation on user authentication</a>. For example, to configure user authentication with <a href="http://httpd.apache.org/docs/mod/mod_auth.html">mod_auth</a> (flat files):
<pre>
<Directory /usr/local/apache/htdocs/freeside-asp>
PerlSetVar Global /usr/local/etc/freeside/asp-global/
AuthName Freeside
AuthType Basic
AuthUserFile /usr/local/etc/freeside/htpasswd
require valid-user
</Directory>
</pre>
<li>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 <a href="http://httpd.apache.org/docs/mod/mod_auth.html">mod_auth</a> (flat files):
<ul>
<li>First user:<font size="-1">
<pre>$ su
$ freeside-adduser -c -h /usr/local/etc/freeside/htpasswd <i>username</i></pre></font>
<li>Additional users:<font size="-1">
<pre>$ su
$ freeside-adduser -h /usr/local/etc/freeside/htpasswd <i>username</i></pre></font>
</ul>
<i>(using other auth types, add each user to your <a href="http://httpd.apache.org/docs/misc/FAQ.html#user-authentication">Apache authentication</a> and then run: <tt>freeside-adduser <b>username</b></tt></i>
<li>As the freeside UNIX user, run <tt>bin/fs-setup <b>username</b></tt> to create the database tables, passing the username of a Freeside user you created above:
<pre>
$ su freeside
$ bin/fs-setup <b>username</b>
</pre>
<li><tt>freeside-queued</tt> 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>
|
