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
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
|
<head>
<title>Installation</title>
</head>
<body>
<h1>Installation</h1>
<i>Note: Install Freeside on a firewalled, private server, not a public (web, RADIUS, etc.) server.</i><br><br>
Before installing, you need:
<ul>
<li><a href="http://www.perl.com/">Perl</a>
<li><a href="http://www.apache.org">Apache</a> (<a href="http://www.modssl.org/">mod_ssl</a> or <a href="http://www.apache-ssl.org">Apache-SSL</a> highly recommended)
<li><a href="http://perl.apache.org/">mod_perl</a> (if compiling your own mod_perl, make sure you set the <a href="http://perl.apache.org/guide/install.html#EVERYTHING">EVERYTHING</a>=1 compile-time option)
<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://rsync.samba.org/">rsync</a>
<li>A <b>transactional</b> database engine <a href="http://search.cpan.org/search?mode=module&query=DBD%3A%3A">supported</a> by Perl's <a href="http://dbi.perl.org">DBI</a>.
<ul>
<li><a href="http://www.postgresql.org/">PostgreSQL</a> is recommended (v7or later).
<li><a href="http://www.mysql.com/">MySQL</a> <b>MINIMUM VERSION 4.1</b> is untested but may work. Versions before 4.1 do not support standard SQL subqueries and are <b>NOT SUPPORTED</b>. If you are a developer who wishes to contribute MySQL 3.x/4.0 support, see <a href="http://pouncequick.420.am/rt/Ticket/Display.html?id=438">ticket #438</a> in the bug-tracking system and ask on the -devel mailing list.
<!-- <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 want to use MySQL, you <b>must</b> 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> or <a href="http://www.mysql.com/doc/I/n/InnoDB.html">InnoDB</a>, and set it as the default table type using the <code>--default-table-type=BDB</code> or <code>--default-table-type=InnoDB</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> or <code>default-table-type=InnoDB</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://search.cpan.org/~andk/CPAN/lib/CPAN.pm">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=MD5">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> (<a href="http://search.cpan.org/search?dist=DBD-Pg">DBD::Pg</a> for PostgreSQL, <a href="http://search.cpan.org/search?dist=DBD-mysql">DBD::mysql</a> for MySQL)
<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>
<li><a href="http://search.cpan.org/search?dist=Tie-IxHash">Tie-IxHash</a>
<li><a href="http://search.cpan.org/search?dist=Time-Duration">Time-Duration</a>
<li><a href="http://search.cpan.org/search?dist=HTML-Widgets-SelectLayers">HTML-Widgets-SelectLayers</a>
<li><a href="http://search.cpan.org/search?dist=Storable">Storable</a>
<!-- MyAccounts, maybe only for dev <li><a href="http://search.cpan.org/search?dist=Cache-Cache">Cache::Cache</a> -->
<li><a href="http://search.cpan.org/search?dist=NetAddr-IP">NetAddr-IP</a>
<li><a href="http://search.cpan.org/search?dist=Chart">Chart</a>
<li><a href="http://search.cpan.org/search?dist=ApacheDBI">Apache::DBI</a> <i>(optional but recommended for better webinterface performance)</i>
</ul>
</ul>
Install the Freeside distribution:
<ul>
<li>Add the user and group `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 (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</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.28/DBI.pm">DBI data source</a>, for example, <tt>DBI:Pg: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.28/DBI.pm">DBI manpage</a> and the <a href="http://search.cpan.org/search?mode=module&query=DBD%3A%3A">manpage for your DBD</a> for the exact syntax of your DBI data source.
<li>Set <tt>DB_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>
(or manually, with Postgres:)
<pre>
$ su freeside
$ createdb freeside</pre>
(with MySQL:)
<pre>
$ mysqladmin -u freeside -p create freeside </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>Run a <b>separate</b> iteration of Apache[-SSL] with mod_perl enabled <b>as the freeside user</b>.
</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:
<font size="-1"><pre>
cp aspdocs /usr/local/apache/htdocs/freeside-asp
</pre></font>
<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>:
<font size="-1"><pre>
mkdir /usr/local/etc/freeside/asp-global/
chown freeside /usr/local/etc/freeside/asp-global/
</pre></font>
<li>Copy <tt>htetc/global.asa</tt> to the Global directory:
<font size="-1"><pre>
cp htetc/global.asa /usr/local/etc/freeside/asp-global/global.asa
</pre></font>
<li>Configure Apache for the Global directory and to execute .cgi files using Apache::ASP. For example:
<font size="-1"><pre>
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 Debug 2
PerlSetVar RequestBinaryRead Off
</Directory>
</pre></font>
</ul></td>
<td><ul>
<li>Run <tt>make masondocs</tt>
<li>Copy <tt>masondocs/</tt> to your web server's document space. (For example: <tt>/usr/local/apache/htdocs/freeside-mason</tt>)
<li>Copy <tt>htetc/handler.pl</tt> to <tt>/usr/local/etc/freeside</tt>
<li>Edit <tt>handler.pl</tt> and:
<ul>
<li> set an appropriate <tt>comp_root</tt>, such as <tt>/usr/local/apache/htdocs/freeside-mason</tt>
<li> set an appropriate <tt>data_dir</tt>, such as <tt>/usr/local/etc/freeside/masondata</tt>
</ul>
<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>
PerlModule HTML::Mason
<Directory /usr/local/apache/htdocs/freeside-mason>
<Files ~ (\.cgi|.html)>
SetHandler perl-script
PerlHandler HTML::Mason
</Files>
<Perl>
require "/usr/local/etc/freeside/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>
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
$ <a href="man/bin/freeside-adduser.html">freeside-adduser</a> -c -h /usr/local/etc/freeside/htpasswd <i>username</i></pre></font>
<li>Additional users:<font size="-1">
<pre>$ su
$ <a href="man/bin/freeside-adduser.html">freeside-adduser</a> -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>freeside-setup <b>username</b></tt> to create the database tables, passing the username of a Freeside user you created above:
<pre>
$ su freeside
$ freeside-setup <b>username</b>
</pre>
Alternately, use the -s option to enable shipping addresses: <tt>freeside-setup -s <b>username</b></tt>
<li>As the freeside UNIX user, run <tt>bin/populate-msgcat <b>username</b></tt> (in the untar'ed freeside directory) to populate the message catalog, passing the username of a Freeside user you created above:
<pre>
$ su freeside
$ cd <b>/path/to/freeside/</b>
$ bin/populate-msgcat <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 (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 <tt>make install-init</tt>)
<li>Now proceed to the initial <a href="admin.html">administration</a> of your installation.
</ul>
</body>
|
