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
209
210
211
212
213
214
|
<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>, minimum version 5.005_03. (5.8.3 for the integrated RT ticketing)
<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>Optional, enables typeset invoices: teTeX and Ghostscript (included with most distributions).
<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 (v7.2 or later, 7.4 or later recommended).
<li> <a href="http://www.mysql.com/">MySQL</a> is <b>not currently supported</b>. <FONT SIZE="-1"><i>Developers intersted in maintaining MySQL support are welcome to ask on the -devel mailing list; many things work, but MySQL support needs a maintainer to update it for recent (and future) changes.</i></FONT>
<!-- <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>.
<!-- <li>MySQL has been reported to work.
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. 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/I/n/InnoDB.html">InnoDB</a>. Set it as the default table type using the <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=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>
<i>Note: the above only applies to the database used by the Freeside software itself. Freeside can integrate with RADIUS and other servers running MySQL <!--(any version)--> or any other DBI-supported database.</i>
<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/dist/Array-PrintCols">Array-PrintCols</a>
<li><a href="http://search.cpan.org/dist/Term-Query">Term-Query</a> (make test broken; install manually) -->
<li><a href="http://search.cpan.org/dist/MIME-Base64">MIME-Base64</a>
<li><a href="http://search.cpan.org/dist/Digest-MD5">Digest-MD5</a>
<!-- <li><a href="http://search.cpan.org/dist/MD5">MD5</a> -->
<li><a href="http://search.cpan.org/dist/URI">URI</a>
<li><a href="http://search.cpan.org/dist/HTML-Tagset">HTML-Tagset</a>
<li><a href="http://search.cpan.org/dist/HTML-Parser">HTML-Parser</a>
<li><a href="http://search.cpan.org/dist/libnet">libnet</a>
<li><a href="http://search.cpan.org/dist/Locale-Codes">Locale-Codes</a>
<li><a href="http://search.cpan.org/dist/Net-Whois-Raw">Net-Whois-Raw</a>
<li><a href="http://search.cpan.org/dist/libwww-perl">libwww-perl</a>
<li><a href="http://search.cpan.org/dist/Business-CreditCard">Business-CreditCard</a>
<!-- <li><a href="http://search.cpan.org/dist/Data-ShowTable">Data-ShowTable</a> -->
<li><a href="http://search.cpan.org/dist/MailTools">MailTools</a>
<li><a href="http://search.cpan.org/dist/TimeDate">TimeDate</a>
<li><a href="http://search.cpan.org/dist/DateManip">DateManip</a>
<li><a href="http://search.cpan.org/dist/File-CounterFile">File-CounterFile</a>
<li><a href="http://search.cpan.org/dist/FreezeThaw">FreezeThaw</a>
<li><a href="http://search.cpan.org/dist/String-Approx">String-Approx</a>
<li><a href="http://search.cpan.org/dist/Text-Template">Text-Template</a>
<li><a href="http://search.cpan.org/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/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/dist/DBIx-DataSource">DBIx-DataSource</a> -->
<li><a href="http://search.cpan.org/dist/DBIx-DBSchema">DBIx-DBSchema</a>
<li><a href="http://search.cpan.org/dist/Net-SSH">Net-SSH</a>
<li><a href="http://search.cpan.org/dist/String-ShellQuote">String-ShellQuote</a>
<li><a href="http://search.cpan.org/dist/Net-SCP">Net-SCP</a>
<li><a href="http://www.masonhq.com/">HTML::Mason</a> (recommended, enables full functionality) or <a href="http://www.apache-asp.org/">Apache::ASP</a> (deprecated, integrated RT ticketing will not be available)
<li><a href="http://search.cpan.org/dist/Tie-IxHash">Tie-IxHash</a>
<li><a href="http://search.cpan.org/dist/Time-Duration">Time-Duration</a>
<li><a href="http://search.cpan.org/dist/HTML-Widgets-SelectLayers">HTML-Widgets-SelectLayers</a>
<li><a href="http://search.cpan.org/dist/Storable">Storable</a>
<li><a href="http://search.cpan.org/dist/Cache-Cache">Cache::Cache</a>
<li><a href="http://search.cpan.org/dist/NetAddr-IP">NetAddr-IP</a>
<li><a href="http://search.cpan.org/dist/Chart">Chart</a>
<li><a href="http://search.cpan.org/dist/Crypt-PasswdMD5">Crypt::PasswdMD5</a>
<li><a href="http://search.cpan.org/dist/Locale-SubCountry">Locale::SubCountry</a>
<li><a href="http://search.cpan.org/dist/Frontier-RPC">Frontier::RPC</a>
<li><a href="http://search.cpan.org/dist/Text-CSV_XS">Text::CSV_XS</a>
<li><a href="http://search.cpan.org/dist/Spreadsheet-WriteExcel">Spreadsheet::WriteExcel</a>
<li><a href="http://search.cpan.org/dist/IO-stringy">IO-stringy (IO::Scalar)</a>
<li><a href="http://search.cpan.org/dist/Frontier-RPC">Frontier::RPC (Frontier::RPC2)</a>
<li><a href="http://search.cpan.org/dist/MIME-tools">MIME::Entity (MIME-tools)</a>
<li><a href="http://search.cpan.org/dist/IPC-Run3">IPC::Run3</a>
<li><a href="http://search.cpan.org/dist/Term-ReadKey">Term::ReadKey</a>
<!-- <li><a href="http://search.cpan.org/dist/Crypt-YAPassGen">Crypt::YAPassGen</a> -->
<li><a href="http://search.cpan.org/search?mode=module&query=MIME::Entity">Fax::Hylafax::Client</a> <i>(Required if using FAX invoice destinations)</i>
<li><a href="http://search.cpan.org/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:
<ul>
<li>with Postgres:
<pre>
$ su freeside
$ createdb -E sql_ascii freeside</pre>
<li>with MySQL:
<pre>
$ mysqladmin -u freeside -p create freeside </pre>
</ul>
<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>.
<li>Edit the <tt>Makefile</tt> and set <tt>TEMPLATE</tt> to <tt>asp</tt> or <tt>mason</tt>. Also set <tt>FREESIDE_DOCUMENT_ROOT</tt>.
<li>Run <tt> make install-docs</tt>.
</ul>
<table>
<tr>
<th>Mason (recommended)</th><th>Apache::ASP (deprecated)</th>
</tr>
<tr>
<td valign="top"><ul>
<li>Configure Apache:
<font size="-1"><pre>
PerlModule HTML::Mason
# your freeside docuemnt root
<Directory /var/www/freeside>
<Files ~ (\.cgi|\.html)>
AddHandler perl-script .cgi .html
PerlHandler HTML::Mason
</Files>
<Perl>
require "/usr/local/etc/freeside/handler.pl";
</Perl>
</Directory>
</pre></font>
</ul></td>
<td valign="top"><ul>
<li>Configure Apache:
<font size="-1"><pre>
PerlModule Apache::ASP
# your freeside document root
<Directory /var/www/freeside>
<Files ~ (\.cgi|\.html)>
AddHandler perl-script .cgi .html
PerlHandler Apache::ASP
</Files>
<Perl>
$MLDBM::RemoveTaint = 1;
</Perl>
PerlSetVar Global /usr/local/etc/freeside/asp-global/
PerlSetVar Debug 2
PerlSetVar RequestBinaryRead Off
# your freeside document root
PerlSetVar IncludesDir /var/www/freeside
</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), add something like the following to your Apache httpd.conf file, adjusting for your actual paths:
<pre>
#your freeside document root
<Directory /var/www/freeside>
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>Create the Freeside system users:
<pre>$ su
# <a href="man/bin/freeside-adduser.html">freeside-adduser</a> fs_queue
# <a href="man/bin/freeside-adduser.html">freeside-adduser</a> fs_selfservice</pre>
<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>
|
