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.

• Proceed to the initial administration of your installation.

• After doing the initial administration, do some cursory testing, including generating and viewing typeset invoices (to test pslatex).

• Don't forget to prepare your installation for Disaster Recovery

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