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

From Freeside
Jump to: navigation, search
m (→‎Installation)
m (→‎Status: Updating the status to match reality.)
 
(26 intermediate revisions by 2 users not shown)
Line 10: Line 10:
  
 
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.
 
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===
 
===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=
 +
 +
== Basic setup and Apache webserver ==
  
 
* Install SLES on your target machine.
 
* Install SLES on your target machine.
Line 21: Line 25:
 
* SSH in as root.
 
* 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.
+
* 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.
  
 
* Also add an update source if you're using a separate repo for updates.
 
* 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.
+
* At the command line enter:
−
** 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 needed.
+
<pre>
 +
yast2 --install apache2-mod_perl
 +
yast2 http-server modules enable=ssl,perl
 +
</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.
 +
 
 +
Next, use the template in /etc/apache2/vhosts.d to create an SSL configuration file for use with Apache:
  
 
<pre>
 
<pre>
Line 37: 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 ==
  
 
* Install the zypper catalog manager:
 
* Install the zypper catalog manager:
Line 53: Line 67:
  
 
You might have to repeat this several times as updating zypper itself may result in more updates becoming available.
 
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:
 
* Use zypper to install postgresql-server if the database server is going to be running on the same machine as Freeside:
Line 72: Line 88:
 
</pre>
 
</pre>
  
−
* Use zypper to add the Freeside repo:
+
* If the database server is going to be running elsewhere, you probably still want the psql command-line client:
  
 
<pre>
 
<pre>
−
zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/stable/x86_64
+
zypper install postgresql
 
</pre>
 
</pre>
  
−
for the stable version, or:
+
== Freeside setup ==
  
 +
* Use zypper to add the Freeside repo:
 +
 +
=== 1.7.3 Stable repository ===
 +
 +
i386 (32-bit):
 
<pre>
 
<pre>
−
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/stable/i386
 
</pre>
 
</pre>
  
−
for a recent CVS build. (This option is really only useful if you have access to the Freeside RPM build system.)
+
x86_64 (64-bit):
 +
<pre>
 +
zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/stable/x86_64
 +
</pre>
  
−
* Update MailTools to 2.x:
+
=== 1_7_BRANCH testing repository ===
  
 +
i386 (32-bit):
 
<pre>
 
<pre>
−
zypper install perl-MailTools
+
zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/testing/i386
 
</pre>
 
</pre>
  
−
and answer 'y'.
+
x86_64 (64-bit):
−
 
+
<pre>
−
If this step fails (zypper refuses to install anything), start yast2 and turn off synchronization of the Install Source to ZenWorks. Turn it back on again once you've completed the Freeside installation.
+
zypper service-add http://freeside.biz/~rsiddall/repo/sles/10/freeside-1.7/testing/x86_64
 +
</pre>
  
 
* Install Freeside:
 
* Install Freeside:
Line 104: Line 130:
 
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.
 
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.  (I haven't tried this yet.)
+
* Install Business::OnlinePayment gateways:
  
 
<pre>
 
<pre>
 
zypper install perl-Business-OnlinePayment-AuthorizeNet
 
zypper install perl-Business-OnlinePayment-AuthorizeNet
 
</pre>
 
</pre>
 +
 +
* 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 <code><nowiki>perl-DBI</nowiki></code> and <code><nowiki>perl-MailTools</nowiki></code>, do the following.
 +
 +
<pre>
 +
zypper search perl-MailTools
 +
</pre>
 +
 +
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:
 
* Work down the final steps to bring up a Freeside installation:
Line 115: Line 153:
 
su postgres -c 'createuser -P freeside'
 
su postgres -c 'createuser -P freeside'
 
su freeside -c 'createdb -E sql_ascii freeside'
 
su freeside -c 'createdb -E sql_ascii freeside'
−
su freeside -c 'freeside-setup -d example.com'
+
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 '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'
 
su freeside -c '/usr/sbin/htpasswd2 /etc/freeside/htpasswd ivan'
 
</pre>
 
</pre>
  
−
* 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.
+
A failure in freeside-setup may indicate a problem with your Freeside repository. See the section on troublesome RPMs.
−
 
 
−
Also in /etc/apache2/uid.conf, change Group from freeside to www.
 
−
 
 
−
Also, 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 temporarily:
+
* Restart the web server
  
 
<pre>
 
<pre>
−
unset TEXINPUTS
 
 
service apache2 restart
 
service apache2 restart
 
</pre>
 
</pre>
  
−
* Try bringing up Freeside in the web browser.  Do some cursory testing, including generating and viewing typeset invoices (to test LaTex).
+
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 140: Line 173:
  
 
* Proceed to the initial [[Freeside:1.7:Documentation:Administration | administration]] of your installation.
 
* Proceed to the initial [[Freeside:1.7:Documentation:Administration | 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 [[Freeside:1.7:Documentation:DisasterRecovery|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:
 +
 +
<pre>
 +
zypper update -t package
 +
</pre>
 +
 +
answer any questions about conflicts, and confirm the installation of the updated RPMs.
 +
 +
* 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 12: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
Retrieved from "https://secure.freeside.biz/mediawiki/index.php?title=Freeside:1.7:Documentation:InstallingUsingYaST&oldid=4565"