Difference between revisions of "Freeside:1.7:Documentation:InstallingUsingYaST"

From Freeside
Jump to: navigation, search
m (Should be http-server, not http_server)
m (Status: Updating the status to match reality.)
 
(7 intermediate revisions by the same user not shown)
Line 15: Line 15:
 
===Status===
 
===Status===
  
The YaST version of Freeside does not include Request Tracker at this time.  The self-service interface conflicts with the main server installation and has been temporarily removed from the repository.  The MySQL backend has not yet been tested.  Only the 1.7 branch has been tested.  The version and release of the YaST package is shown in the "Billing Main" page in Freeside.
+
The YaST version of Freeside does not include Request Tracker at this time.  The self-service interface no longer conflicts with the main server installation, but has been temporarily moved to its own repository.  The MySQL backend has not yet been tested.  Only the 1.7 branch has been tested.  The version and release of the YaST package is shown in the "Billing Main" page in Freeside.
  
 
=Installation=
 
=Installation=
Line 24: Line 24:
  
 
* SSH in as root.
 
* SSH in as root.
 +
 +
* If you are installing to a machine behind a proxy server, run <code>yast2</code> and select <code>Network Settings : Proxy</code> and enter the proxy details so that YaST can access external repositories.  (You can also set the proxy settings from the command line using <code>yast2 proxy</code>.)
  
 
* Run "yast2" and select "Software : Installation Source", or (faster) enter "yast2 inst_source", and make sure the SLES repo is present.  If not click Add and add the URL of the repo.
 
* Run "yast2" and select "Software : Installation Source", or (faster) enter "yast2 inst_source", and make sure the SLES repo is present.  If not click Add and add the URL of the repo.
Line 32: Line 34:
  
 
<pre>
 
<pre>
 +
yast2 --install apache2-mod_perl
 
yast2 http-server modules enable=ssl,perl
 
yast2 http-server modules enable=ssl,perl
 
</pre>
 
</pre>
  
 
* Setup SSL.  SLES does not ship with a working SSL configuration for Apache2.  You'll need to configure a virtual host and configure SSL on that virtual host.  First, scp the server certificate and key to /etc/apache2/ssl.{crt,key}, and copy any certificate authority bundles supplied by your certificate provider.
 
* Setup SSL.  SLES does not ship with a working SSL configuration for Apache2.  You'll need to configure a virtual host and configure SSL on that virtual host.  First, scp the server certificate and key to /etc/apache2/ssl.{crt,key}, and copy any certificate authority bundles supplied by your certificate provider.
 +
 +
Next, use the template in /etc/apache2/vhosts.d to create an SSL configuration file for use with Apache:
  
 
<pre>
 
<pre>
Line 42: Line 47:
 
vi freeside-ssl.conf # Uncomment and correct ServerName, ServerAdmin, and any SSL file locations
 
vi freeside-ssl.conf # Uncomment and correct ServerName, ServerAdmin, and any SSL file locations
 
</pre>
 
</pre>
 +
 +
ServerName can be the same as the main host name of the SuSE machine.
  
 
== Zypper setup ==  
 
== Zypper setup ==  
Line 114: Line 121:
 
zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/testing/x86_64
 
zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/testing/x86_64
 
</pre>
 
</pre>
 
* Update MailTools to 2.x:
 
 
<pre>
 
zypper install perl-MailTools
 
</pre>
 
 
and answer 'y'.
 
 
If this step fails (zypper refuses to install anything or wants to install MailTools 1.67), start yast2 and turn off synchronization of the Install Source to ZenWorks.  Turn it back on again once you've completed the Freeside installation.
 
 
If that still doesn't work, download perl-MailTools and perl-DBI manually from your repository source above, and install them with <code>rpm -Uvh filename.rpm</code>.
 
 
  
 
* Install Freeside:
 
* Install Freeside:
Line 142: Line 136:
 
</pre>
 
</pre>
  
* Work down the final steps to bring up a Freeside installation:
+
* Optionally, check for troublesome RPMs:
 
 
<pre>
 
su postgres -c 'createuser -P freeside'
 
su freeside -c 'createdb -E sql_ascii freeside'
 
su freeside -c 'freeside-setup -d example.com'
 
su freeside -c 'for i in fs_queue fs_daily fs_selfservice ivan; do freeside-adduser -g 1 $i; done'
 
su freeside -c '/usr/sbin/htpasswd2 /etc/freeside/htpasswd ivan'
 
</pre>
 
 
 
== Errata ==
 
  
* To fix a current bug in the freeside-mason RPM generation, go into /etc/apache2/conf.d/freeside-base2.conf and replace %%%FREESIDE_CONF%%% with /etc/freeside.
+
You may wish to spot check the version of a couple of RPMs at this point to detect problems now before the final stages of installation fail.
  
* In /etc/apache2/uid.conf, change Group from freeside to www.
+
For each of <code><nowiki>perl-DBI</nowiki></code> and <code><nowiki>perl-MailTools</nowiki></code>, do the following.
 
 
* In /etc/freeside/handler.pl, remove the 3.29 following "use CGI" as this is only required for Request Tracker.
 
 
 
* To get pslatex to work if you click on "Bill Now" in the Freeside GUI:
 
  
 
<pre>
 
<pre>
echo "unset TEXINPUTS" >> /etc/profile.local
+
zypper search perl-MailTools
 
</pre>
 
</pre>
  
and apply the same change to the current session:
+
which should show the installed version, marked with an 'i' in the left column, as being the same as the one on the Freeside repository.  If the installed version came from the SLES repository, see the section on troublesome RPMs.
 +
 
 +
* Work down the final steps to bring up a Freeside installation:
  
 
<pre>
 
<pre>
unset TEXINPUTS
+
su postgres -c 'createuser -P freeside'
 +
su freeside -c 'createdb -E sql_ascii freeside'
 +
su freeside -c 'freeside-setup -d example.com'
 +
su freeside -c 'for i in fs_queue fs_daily fs_selfservice ivan; do freeside-adduser -g 1 $i; done'
 +
su freeside -c '/usr/sbin/htpasswd2 /etc/freeside/htpasswd ivan'
 
</pre>
 
</pre>
  
* Edit /etc/init.d/apache2 and insert a line "unset TEXINPUTS" immediately after the line beginning "export ${!APACHE_*}"(If you run a daily cron job to execute freeside-daily, no further changes should be necessary for typeset invoices to work.)
+
A failure in freeside-setup may indicate a problem with your Freeside repositorySee the section on troublesome RPMs.
  
 
* Restart the web server
 
* Restart the web server
Line 179: Line 165:
 
service apache2 restart
 
service apache2 restart
 
</pre>
 
</pre>
 +
 +
If the web server fails to start due to a problem in /etc/freeside/handler.pl, it may indicate a problem with your Freeside repository.  See the section on troublesome RPMs.
  
 
= Finalizing the installation =
 
= Finalizing the installation =
Line 201: Line 189:
  
 
* If there have been any schema changes, run <code><nowiki>/usr/bin/freeside-update</nowiki></code>.
 
* If there have been any schema changes, run <code><nowiki>/usr/bin/freeside-update</nowiki></code>.
 +
 +
= Installing the Self-Service Interface =
 +
 +
On a new SLES system, complete the steps up to and including the "zypper installation" above.  (You can skip installing mod_perl and omit "perl" in the list of Apache modules to enable.)
 +
 +
(Installing the self-service interface on the same system as the Freeside billing server is not recommended for security reasons.  However, it is possible to install self-service by following these instructions after completing the billing server installation.)
 +
 +
* Use zypper to add the Freeside Self-Service repo:
 +
 +
=== 1.7.3 Stable repository ===
 +
 +
i386 (32-bit):
 +
<pre>
 +
zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/stable/self-service/i386
 +
</pre>
 +
 +
x86_64 (64-bit):
 +
<pre>
 +
zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/stable/self-service/x86_64
 +
</pre>
 +
 +
=== 1_7_BRANCH testing repository ===
 +
 +
i386 (32-bit):
 +
<pre>
 +
zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/testing/self-service/i386
 +
</pre>
 +
 +
x86_64 (64-bit):
 +
<pre>
 +
zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/testing/self-service/x86_64
 +
</pre>
 +
 +
* Install Freeside Self-Service:
 +
 +
<pre>
 +
zypper install freeside-selfservice
 +
</pre>
 +
 +
This will install the core self-service Perl modules, the self-service CGI scripts, and an Apache configuration file that makes the self-service available at https://www.example.com/selfservice/selfservice.cgi.  If you wish to configure Apache differently, either edit the configuration file after installation or install freeside-selfservice-cgi instead of freeside-selfservice to skip the configuration file installation.
 +
 +
* Restart the Apache web server:
 +
 +
<pre>
 +
service apache2 restart
 +
</pre>
 +
 +
* On your billing server, check the value of SELFSERVICE_MACHINES in /etc/default/freeside or /etc/sysconfig/freeside, make sure the freeside user can SSH into each of the self-service machines, and start the freeside service.  Look at the log file for the self-service daemon to ensure it's connecting correctly to the client.  (Note that RPM-based self-service installations have the client daemon the billing server connects to located at /usr/sbin/freeside-selfservice-clientd, not under /usr/local/sbin.  You may have to edit freeside-selfservice-server on your billing machine to match.)
 +
 +
= Troublesome RPMs =
 +
 +
You may have trouble getting yast2/zypper to install the newer versions of RPMs from the Freeside repository since libzypp considers build architecture to be more important than software version.  This problem is more prevalent on i386 systems where it's easy to build an i386 RPM for which SLES has an older, i586, version.  However, you may also see it where you build a noarch RPM to replace a SLES x86_64 RPM.
 +
 +
If zypper refuses to install the newer version from the Freeside repository, the most likely problem is that libzypp prefers the architecture of the RPM on the SLES repository.  You can confirm this by running (for perl-MailTools):
 +
 +
<pre>
 +
zypper -vv install perl-MailTools
 +
</pre>
 +
 +
The last couple of lines will show you which of the available RPMs zypper is selecting, and why.
 +
 +
If you don't have time to fix your Freeside repository (i.e. to rebuild the RPM with the same or better BuildArch than that used for the equivalent SLES RPM), you can always download the RPMs manually from your repository source above, and install them with <code>rpm -Uvh filename.rpm</code>.  The output of <code>zypper search perl-MailTools</code> gives you the base URL of the repository, the RPM name, version/release, and architecture, which you can piece together into the URL of the RPM:
 +
 +
<pre>
 +
wget <base_url>/<rpm_name>-<rpm_version/release>.<arch>.rpm
 +
</pre>

Latest revision as of 13:46, 14 April 2009

Introduction

Warnings!

The YaST installation of Freeside is experimental! The instructions below may be incomplete or incorrect and are subject to change. You should only attempt to use the YaST installation if you are prepared to work around omissions and inaccuracies, and can recover data in the event of a loss.

Information

YaST is the installer on the SuSE Linux distributions: Novell's SuSE Enterprise Linux Server (SLES) and OpenSuSE. The Freeside repository is a repomd, i.e. RPM-based, repository.

Installing the YaST version of Freeside may not be a good idea if you plan to do development on Freeside as the RPMs may not include all the files supplied in the tarball.

YaST tends to try to pull in a large set of conflicting RPMs, so any attempt to use YaST or zypper may result in you having to work through a slew of warnings and tell YaST not to pull in RPMs you didn't specify, or which yum would have concluded were not required.

Status

The YaST version of Freeside does not include Request Tracker at this time. The self-service interface no longer conflicts with the main server installation, but has been temporarily moved to its own repository. The MySQL backend has not yet been tested. Only the 1.7 branch has been tested. The version and release of the YaST package is shown in the "Billing Main" page in Freeside.

Installation

Basic setup and Apache webserver

  • Install SLES on your target machine.
  • SSH in as root.
  • If you are installing to a machine behind a proxy server, run yast2 and select Network Settings : Proxy and enter the proxy details so that YaST can access external repositories. (You can also set the proxy settings from the command line using yast2 proxy.)
  • Run "yast2" and select "Software : Installation Source", or (faster) enter "yast2 inst_source", and make sure the SLES repo is present. If not click Add and add the URL of the repo.
  • Also add an update source if you're using a separate repo for updates.
  • At the command line enter:
yast2 --install apache2-mod_perl
yast2 http-server modules enable=ssl,perl
  • Setup SSL. SLES does not ship with a working SSL configuration for Apache2. You'll need to configure a virtual host and configure SSL on that virtual host. First, scp the server certificate and key to /etc/apache2/ssl.{crt,key}, and copy any certificate authority bundles supplied by your certificate provider.

Next, use the template in /etc/apache2/vhosts.d to create an SSL configuration file for use with Apache:

cd /etc/apache2/vhosts.d
cp -p vhost-ssl.template freeside-ssl.conf
vi freeside-ssl.conf # Uncomment and correct ServerName, ServerAdmin, and any SSL file locations

ServerName can be the same as the main host name of the SuSE machine.

Zypper setup

  • Install the zypper catalog manager:
yast2 --install zypper

as zypper has a better CLI interface than YaST.

  • Use zypper to update the whole system?
zypper update

You might have to repeat this several times as updating zypper itself may result in more updates becoming available.

PostgreSQL setup

  • Use zypper to install postgresql-server if the database server is going to be running on the same machine as Freeside:
zypper install postgresql-server
  • Set PostgreSQL to run on startup:
chkconfig --add postgresql

and start it now

service postgresql start
  • If the database server is going to be running elsewhere, you probably still want the psql command-line client:
zypper install postgresql

Freeside setup

  • Use zypper to add the Freeside repo:

1.7.3 Stable repository

i386 (32-bit):

zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/stable/i386

x86_64 (64-bit):

zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/stable/x86_64

1_7_BRANCH testing repository

i386 (32-bit):

zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/testing/i386

x86_64 (64-bit):

zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/testing/x86_64
  • Install Freeside:
zypper install freeside-postgresql

If zypper complains that it can't find a provider of "freeside" or "freeside-mason", it means that your repo is missing Perl module RPMs that the freeside or freeside-mason RPMs require. You can keep telling zypper to ignore that requirement, which will cause zypper to enumerate the missing modules.

  • Install Business::OnlinePayment gateways:
zypper install perl-Business-OnlinePayment-AuthorizeNet
  • Optionally, check for troublesome RPMs:

You may wish to spot check the version of a couple of RPMs at this point to detect problems now before the final stages of installation fail.

For each of perl-DBI and perl-MailTools, do the following.

zypper search perl-MailTools

which should show the installed version, marked with an 'i' in the left column, as being the same as the one on the Freeside repository. If the installed version came from the SLES repository, see the section on troublesome RPMs.

  • Work down the final steps to bring up a Freeside installation:
su postgres -c 'createuser -P freeside'
su freeside -c 'createdb -E sql_ascii freeside'
su freeside -c 'freeside-setup -d example.com' 
su freeside -c 'for i in fs_queue fs_daily fs_selfservice ivan; do freeside-adduser -g 1 $i; done'
su freeside -c '/usr/sbin/htpasswd2 /etc/freeside/htpasswd ivan'

A failure in freeside-setup may indicate a problem with your Freeside repository. See the section on troublesome RPMs.

  • Restart the web server
service apache2 restart

If the web server fails to start due to a problem in /etc/freeside/handler.pl, it may indicate a problem with your Freeside repository. See the section on troublesome RPMs.

Finalizing the installation

  • Go to https://your.host.name/freeside and log in.
  • After doing the initial administration, do some cursory testing, including generating and viewing typeset invoices (to test pslatex).

Updating the Installation

  • Since the Freeside repository does not contain patch RPMs and zypper defaults to using patch RPMs, the installation can be updated with:
zypper update -t package

answer any questions about conflicts, and confirm the installation of the updated RPMs.

  • If there have been any schema changes, run /usr/bin/freeside-update.

Installing the Self-Service Interface

On a new SLES system, complete the steps up to and including the "zypper installation" above. (You can skip installing mod_perl and omit "perl" in the list of Apache modules to enable.)

(Installing the self-service interface on the same system as the Freeside billing server is not recommended for security reasons. However, it is possible to install self-service by following these instructions after completing the billing server installation.)

  • Use zypper to add the Freeside Self-Service repo:

1.7.3 Stable repository

i386 (32-bit):

zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/stable/self-service/i386

x86_64 (64-bit):

zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/stable/self-service/x86_64

1_7_BRANCH testing repository

i386 (32-bit):

zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/testing/self-service/i386

x86_64 (64-bit):

zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/testing/self-service/x86_64
  • Install Freeside Self-Service:
zypper install freeside-selfservice

This will install the core self-service Perl modules, the self-service CGI scripts, and an Apache configuration file that makes the self-service available at https://www.example.com/selfservice/selfservice.cgi. If you wish to configure Apache differently, either edit the configuration file after installation or install freeside-selfservice-cgi instead of freeside-selfservice to skip the configuration file installation.

  • Restart the Apache web server:
service apache2 restart
  • On your billing server, check the value of SELFSERVICE_MACHINES in /etc/default/freeside or /etc/sysconfig/freeside, make sure the freeside user can SSH into each of the self-service machines, and start the freeside service. Look at the log file for the self-service daemon to ensure it's connecting correctly to the client. (Note that RPM-based self-service installations have the client daemon the billing server connects to located at /usr/sbin/freeside-selfservice-clientd, not under /usr/local/sbin. You may have to edit freeside-selfservice-server on your billing machine to match.)

Troublesome RPMs

You may have trouble getting yast2/zypper to install the newer versions of RPMs from the Freeside repository since libzypp considers build architecture to be more important than software version. This problem is more prevalent on i386 systems where it's easy to build an i386 RPM for which SLES has an older, i586, version. However, you may also see it where you build a noarch RPM to replace a SLES x86_64 RPM.

If zypper refuses to install the newer version from the Freeside repository, the most likely problem is that libzypp prefers the architecture of the RPM on the SLES repository. You can confirm this by running (for perl-MailTools):

zypper -vv install perl-MailTools

The last couple of lines will show you which of the available RPMs zypper is selecting, and why.

If you don't have time to fix your Freeside repository (i.e. to rebuild the RPM with the same or better BuildArch than that used for the equivalent SLES RPM), you can always download the RPMs manually from your repository source above, and install them with rpm -Uvh filename.rpm. The output of zypper search perl-MailTools gives you the base URL of the repository, the RPM name, version/release, and architecture, which you can piece together into the URL of the RPM:

wget <base_url>/<rpm_name>-<rpm_version/release>.<arch>.rpm