Revision as of 10:54, 16 December 2008

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 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.

Installation

Basic setup and Apache webserver

• Install SLES on your target machine.

• SSH in as root.

• Run "yast2", select "Software : Installation 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.

• While still in YaST, select "Network Services : HTTP Server" and walk through the configuration wizard. It will show SSL disabled.
  • Enable "Perl Scripting," which is mod_perl.
  • Set "HTTP Service" to "Enabled"
  • In the 5th screen, select "HTTP Server Expert Configuration". Then you can select Server Modules, move down to "ssl" and select the toggle button to enable SSL.

• Exit YaST and 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.

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

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

• Update MailTools to 2.x:

zypper install perl-MailTools

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 rpm -Uvh filename.rpm.

• 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

• 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'

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.

• In /etc/apache2/uid.conf, change Group from freeside to www.

• 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:

echo "unset TEXINPUTS" >> /etc/profile.local

and apply the same change to the current session:

unset TEXINPUTS

• 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.)

• Restart the web server

service apache2 restart

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).