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

From Freeside
Jump to: navigation, search
m (Reverted edits by MishelayBN2 (Talk); changed back to last version by Ivan)
 
(113 intermediate revisions by 10 users not shown)
Line 5: Line 5:
  
 
==Information==
 
==Information==
−
RPM is a build-once, install-many package manager for system management. Originally for RedHat, it is now used on a wide range of Linux distros including Fedora, SUSE, etc. Well-structured RPMs include dependency information that RPM can use to warn you that additional components are required. Tools such as yum and apt-get (RPM version) can use this dependency information to download additional components from a repository and include them in the installation. This has the potential to make installing Freeside almost as easy as installing a Windows program.
+
 
 +
The currently available packages are for the i386 and x86_64 architectures. The packages are built on CentOS 5 and currently tested on CentOS and RHEL 5. Packages for CentOS/RHEL 4 are no longer available.
 +
 
 +
Packagers for other distributions are welcome; see [[Freeside:1.7:Documentation:CreatingRPMRepo|creating RPM repositories]].  You can also read about our own [[Freeside:1.7:Documentation:RPMBuildSystem|RPM build system]].
 +
 
 
Installing the RPM 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 RPM 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.
 +
 +
===Status===
 +
 +
The RPM version of Freeside does not include Request Tracker at this time.  The self-service RPM has not been fully tested.  Both PostgreSQL and MySQL back-end databases should work.  The version and release of the RPM were shown in the "Billing Main" page in Freeside, but we concluded this was misleading.  You can now get the version and release by entering <code>rpm -q freeside</code> at the command line.
  
 
=Installation=
 
=Installation=
  
−
==Installation using RPM==
+
RPM installation can preferably be done with a tool such as YUM or APT (or up2date on RHEL).  As a last resort, you can install with RPM directly.
−
Installation is much easier if you have a repository that works with a tool such as [[#yum|yum]] or [[#apt|apt-get]]. If you only have rpm and wish to use that, enter:
+
 
 +
==Installing using yum==
 +
=== Setup YUM ===
 +
* If you are installing to a machine behind a proxy server, you may need to set up the proxy directives in /etc/yum.conf for yum to work correctly.
 +
* Make sure the yum priorities plugin is installed by running <code>yum install yum-plugin-priorities</code> for CentOS v4, or <code>yum install yum-priorities</code> for CentOS v5.
 +
* Make sure the yum priorities plugin is enabled by editing the <code>/etc/yum/pluginconf.d/priorities.conf</code> file, and ensuring that it contains the following lines:
 +
  [main]
 +
  enabled=1
 +
* Edit <code>/etc/yum.repso.d/CentOS-Base.repo</code>, adding the following lines to the <nowiki>[base] and [update] sections, and adding the [centosplus] section:</nowiki>
 +
 
 +
<pre>[base]
 +
exclude=php* httpd* MySQL* mysql* perl perl-suidperl unixODBC* mod_auth_mysql mod_auth_pgsql mod_perl mod_perl-devel mod_ssl
 +
priority=1
 +
 
 +
[update]
 +
exclude=php* httpd* MySQL* mysql* perl perl-suidperl unixODBC* mod_auth_mysql mod_auth_pgsql mod_perl mod_perl-devel mod_ssl
 +
priority=1
 +
 
 +
[centosplus]
 +
enabled=1
 +
priority=2
 +
</pre>
 +
 
 +
* Select a repository containing the required RPMs, and add the repository to a new file in your /etc/yum.repo.d directory or directly to the /etc/yum.conf file. If no such repository exists, you can [[Freeside:1.7:Documentation:CreatingRPMRepo|create your own]].
 +
 
 +
==== 1.7 pre-release repository ====
 +
 
 +
This repository contains <b>only</b> the Freeside RPMs for release candidates.  Use the testing repository for all of the required Perl RPMs.
 +
 
 
<pre>
 
<pre>
−
rpm -Uvh --test freeside-1.7.3-1.noarch.rpm \
+
cd /etc/yum.repos.d
−
freeside-mason-1.7.3-1.noarch.rpm \
+
wget http://www.freeside.biz/~rsiddall/freeside.repo
−
freeside-postgresql-1.7.3-1.noarch.rpm \
 
−
perl-Business-OnlinePayment-AuthorizeNet-3.17-1.i386.rpm
 
 
</pre>
 
</pre>
−
Where:
+
 
−
* 1.7.3-1 is the version of Freeside and the release of the RPM.  Change this if necessary.
+
The repository definition file defines a testing, stable, and a pre-release repository.  All of these are disabled by default, so
−
* postgresql is the database you wish to use as the Freeside back-end.  Replace freeside-postgresql with freeside-mysql if you wish to use MySQL. See the main installation document for which databases are supported.
+
you either need to include <code>--enablerepo=freeside-testing --enablerepo=freeside-prerelease</code> when invoking yum, or just edit the file and enable the repositories you want to use by changing the <code>enable=0</code> to <code>enable=1</code> in the corresponding section of the file.
−
* Replace AuthorizeNet with the name of the credit card processor you wish to use for real-time transactions. Also replace 3.17-1.i386 with the current version, release, and architecture of the corresponding Business::OnlinePayment RPM.
+
 
−
The command should result in some warnings about unsatisfied dependencies.  Find the corresponding RPMs and add them to the list on the command line. Keep doing this until the command results in no warnings, then issue the command one last time without the --test to actually install all the RPMs.
+
Since the release candidate RPMs have a higher version number than the CVS snapshot builds, yum will install the release candidates instead of the CVS snapshot.  You can verify this after yum completes by entering <code>rpm -q freeside</code> and checking that it's something like <code>freeside-1.7.4rc2-1</code>.
−
Installing the freeside RPM will install the '''[[#freeside-install|freeside-install]]''' command line utility that you can use to finish the installation.
+
 
−
==Installing using yum==
+
==== 1.7 stable repository ====
−
* First, find a repository containing all the required RPMs. If no such repository exists, you can [[#repository|create your own]].
+
 
−
* Next, add the repository to your /etc/yum.repo.d directory or /etc/yum.conf file.
+
Follow the instructions for the 1.7 pre-release repository, but enable the stable repository instead of the pre-release.
−
* Finally, install the required components by issuing the command:
+
 
−
<pre>yum install freeside freeside-mason freeside-postgresql perl-Business-OnlinePayment-AuthorizeNet</pre>
+
==== 1_7_BRANCH repository ====
 +
 
 +
CentOS/RHEL v5 i386: <pre>#Packages used in Freeside
 +
[freeside]
 +
name=Freeside-5
 +
baseurl=http://www.freeside.biz/~ivan/repo/centos/5/freeside-1.7/testing/i386
 +
gpgcheck=1
 +
enabled=1
 +
priority=2
 +
gpgkey=http://www.freeside.biz/~rsiddall/RPM-GPG-KEY-Freeside</pre>
 +
 
 +
CentOS/RHEL v5 x86_64: <pre>#Packages used in Freeside
 +
[freeside]
 +
name=Freeside-5
 +
baseurl=http://www.freeside.biz/~ivan/repo/centos/5/freeside-1.7/testing/x86_64
 +
gpgcheck=1
 +
enabled=1
 +
priority=2
 +
gpgkey=http://www.freeside.biz/~rsiddall/RPM-GPG-KEY-Freeside</pre>
 +
 
 +
=== Install ===
 +
 
 +
* Install the required components by issuing the commands:
 +
<pre>yum install httpd mod_perl mod_ssl perl postgresql-server
 +
yum install perl-File-Temp perl-CGI.pm
 +
yum install freeside freeside-mason freeside-postgresql perl-Business-OnlinePayment-AuthorizeNet</pre>
 
with these changes:
 
with these changes:
 
* Replace posgresql with mysql if you wish to use MySQL instead of PostgreSQL for the main Freeside database.
 
* Replace posgresql with mysql if you wish to use MySQL instead of PostgreSQL for the main Freeside database.
 
* Replace AuthorizeNet with the name of the Business::OnlinePaymet module for the credit card gateway you wish to use.
 
* Replace AuthorizeNet with the name of the Business::OnlinePaymet module for the credit card gateway you wish to use.
 
* Add the RPM name of any additional Business::OnlinePayment gateways you wish to install.
 
* Add the RPM name of any additional Business::OnlinePayment gateways you wish to install.
−
At this point all the required components should be installed and the freeside user account created. You can now complete the installation with [[#freeside-install|freeside-install]].
+
 
−
* If you are using a repository that is normally disabled, use <pre>yum --enablerepo=freeside install ...</pre> where freeside is the name of the repository.
+
At this point all the required components should be installed and the freeside user account created. You can now [[#Finalizing the installation|complete the installation]].
−
If you get an error such as:
+
 
 +
=== Troubleshooting ===
 +
 
 +
* If you are using a repository that is normally disabled, use <code>yum --enablerepo=Freeside-4 install ...</code> where ''Freeside-4'' is the name of the repository.
 +
* If you get an error such as:
 
<pre>
 
<pre>
 
Transaction Check Error:  file /usr/share/man/man3/File::Temp.3pm.gz from install of perl-File-Temp-0.18-1 conflicts with file from package perl-5.8.8-4.el4s1
 
Transaction Check Error:  file /usr/share/man/man3/File::Temp.3pm.gz from install of perl-File-Temp-0.18-1 conflicts with file from package perl-5.8.8-4.el4s1
Line 45: Line 108:
 
This installs the conflicting RPM from yum's cache for the "freeside" repository.
 
This installs the conflicting RPM from yum's cache for the "freeside" repository.
 
You can then retry installing from yum.
 
You can then retry installing from yum.
 +
 +
==Installing using up2date==
 +
 +
Mainly for vanilla RHEL 4; if you are running RHEL 5 or CentOS, the [[#Installing_using_yum|yum]] or [[#Installing_using_APT|apt-get]] instructions may be preferable.
 +
 +
===Setup up2date===
 +
* Import GPG keys:
 +
  rpm --import http://mirror.centos.org/centos/RPM-GPG-KEY-CentOS-5
 +
  rpm --import http://www.freeside.biz/~rsiddall/RPM-GPG-KEY-Freeside
 +
 +
* Select a repository containing the required RPMs and add the repository to your /etc/sysconfig/rhn/sources file. If no such repository exists, you can [[Freeside:1.7:Documentation:CreatingRPMRepo|create your own]].
 +
 +
==== 1_7_BRANCH repository ====
 +
RHEL v5 i386: <pre>yum centosplus http://mirror.centos.org/centos/4/centosplus/i386/
 +
yum freeside http://www.freeside.biz/~ivan/repo/centos/4/freeside-1.7/testing/i386</pre>
 +
 +
RHEL v5 x86_64: <pre>yum centosplus http://mirror.centos.org/centos/4/centosplus/x86_64/
 +
yum freeside http://www.freeside.biz/~ivan/repo/centos/4/freeside-1.7/testing/x86_64</pre>
 +
 +
=== Install ===
 +
 +
* Install the required components by issuing the commands:
 +
<pre>up2date httpd mod_perl mod_ssl perl postgresql-server tetex-latex perl-Digest-SHA1 perl-XML-Parser
 +
up2date perl-File-Temp #this will fail, that's okay for now
 +
rpm -Uvh --force /var/spool/up2date/perl-File-Temp-0.18-1.x86_64.rpm #to force File::Temp 0.18 installation, for now
 +
up2date freeside freeside-mason freeside-postgresql perl-Business-OnlinePayment-AuthorizeNet</pre>
 +
with these changes:
 +
* Replace posgresql with mysql if you wish to use MySQL instead of PostgreSQL for the main Freeside database.
 +
* Replace AuthorizeNet with the name of the Business::OnlinePaymet module for the credit card gateway you wish to use.
 +
* Add the RPM name of any additional Business::OnlinePayment gateways you wish to install.
 +
 +
At this point all the required components should be installed and the freeside user account created. You can now [[#Finalizing the installation|complete the installation]].
 +
 +
=== Troubleshooting ===
 +
 +
* Does up2date show a "freeside" channel when doing <code>up2date --show-channels</code>, but won't install packages from that repository?  Make sure <code>/etc/sysconfig/rhn/up2date</code> has a line designating a blank proxy:
 +
  httpProxy=
 +
 
==Installing using APT==
 
==Installing using APT==
−
* First, find a repository containing all the required RPMs. If no such repository exists, you can [[#repository|create your own]].
+
===Setup APT===
−
* Next, add the repository to your /etc/apt.conf file.
+
Select a repository containing the required RPMs and add the repository to your /etc/apt.conf file.. If no such repository exists, you can [[Freeside:1.7:Documentation:CreatingRPMRepo|create your own]].
−
* Finally, install the required components by issuing the command:
+
====1.7.3 stable repository ====
 +
(not yet available)
 +
====1_7_BRANCH testing repository====
 +
(not yet available)
 +
 
 +
===Install===
 +
* Install the required components by issuing the command:
 
<pre>apt-get install freeside freeside-mason freeside-postgresql perl-Business-OnlinePayment-AuthorizeNet</pre>
 
<pre>apt-get install freeside freeside-mason freeside-postgresql perl-Business-OnlinePayment-AuthorizeNet</pre>
−
At this point all the required components should be installed and the freeside user account created. You can now complete the installation with [[#freeside-install|freeside-install]].
+
with these changes:
−
=Finalizing the installation=
+
* Replace posgresql with mysql if you wish to use MySQL instead of PostgreSQL for the main Freeside database.
−
RPM does little more than installing files and creating users. To allow automated installation and upgrading, well-structured RPMs may not interact with the user. Since part of the Freeside installation is interactive, at some future date a command line utility called '''freeside-install''' will be included in the RPM to help you complete the installation.
+
* Replace AuthorizeNet with the name of the Business::OnlinePaymet module for the credit card gateway you wish to use.
−
For the moment, just work through the standard install, ignoring the steps which are done by the RPM, i.e. installing files and creating the freeside user. The RPM does not do any steps that require entry of a password, or which have to be done after a password is specified.
+
* Add the RPM name of any additional Business::OnlinePayment gateways you wish to install.
−
* You can skip straight to &quot;Allow the freeside user full access to the freeside database,&quot; but be aware that if there are errors in the RPM dependencies, then some of the prerequisites may not be installed.
+
At this point all the required components should be installed and the freeside user account created. You can now [[#Finalizing the installation|complete the installation]].
−
* Then &quot;Add the freeside database to your database engine:&quot;
+
 
−
* Apache configuration is reduced to editing your httpd.conf file as specified in the last bullet point. (This will be automated in a later Freeside RPM.) You'll also have to modify httpd.conf to implement web interface security.
+
==Installation using RPM==
−
* All the final steps to create the first Freeside user, setup the database, populate the message catalog, and start freeside-queued must be done by hand.
+
Installation is much easier if you have a repository that works with a tool such as [[#Installing_using_yum|yum]], [[#Installing_using_APT|apt-get]] or [[#Installing_using_up2date|up2date]]. If you only have rpm and wish to use that, enter:
−
* As with the usual install, you need to do initial administration after completing the install.
+
 
−
=Creating your own repository with Freeside RPMs=
 
−
If you can't find an APT/yum repository for your operating system, you can create your own.
 
−
==Create a build environment matching your target==
 
−
If your target is CentOS 4.x or similar, be aware that the standard mod_perl is 1.99.  You should install an updated httpd, mod_perl, mod_ssl, etc. from the CentOS Plus repository, which also includes an updated PostgreSQL.
 
 
<pre>
 
<pre>
−
yum --enablerepo=centosplus httpd mod_perl mod_ssl postgresql
+
rpm -Uvh --test freeside-1.7.3-1.noarch.rpm \
 +
freeside-mason-1.7.3-1.noarch.rpm \
 +
freeside-postgresql-1.7.3-1.noarch.rpm \
 +
perl-Business-OnlinePayment-AuthorizeNet-3.17-1.i386.rpm
 
</pre>
 
</pre>
−
==Set up your development environment for building RPMs as non-root==
+
Where:
−
You should always build RPMs as a non-root user.
+
* 1.7.3-1 is the version of Freeside and the release of the RPM.  Change this if necessary.
−
* First, create an account to build RPMs:
+
* postgresql is the database you wish to use as the Freeside back-end.  Replace freeside-postgresql with freeside-mysql if you wish to use MySQL. See the main installation document for which databases are supported.
−
<pre>useradd bob</pre>
+
* Replace AuthorizeNet with the name of the credit card processor you wish to use for real-time transactions. Also replace 3.17-1.i386 with the current version, release, and architecture of the corresponding Business::OnlinePayment RPM.
−
* Next, create or import a GPG key with which to sign the RPMs. (Signing is optional but recommended.)
+
The command should result in some warnings about unsatisfied dependencies.  Find the corresponding RPMs and add them to the list on the command line.  Keep doing this until the command results in no warnings, then issue the command one last time without the --test to actually install all the RPMs.
−
* Next, create a .rpmmacros file in that user's home directory:
+
 
−
<pre>su bob
+
At this point all the required components should be installed and the freeside user account created. You can now [[#Finalizing the installation|complete the installation]].
−
vi ~/.rpmmacros
+
 
−
%_topdir /home/bob/redhat
+
=Finalizing the installation=
−
%_signature gpg
+
 
−
%_gpg_path /home/bob/.gnupg
+
* Start the database:
−
%_gpg_name Yourname Here
+
with PostgreSQL
−
</pre>
+
 
−
* Finally, create a set of directories for RPM to use:
+
  chown -R postgres:postgres /var/lib/pgsql
 +
  /sbin/service postgresql start
 +
 
 +
or with MySQL
 +
 
 +
  /sbin/service mysqld start
 +
 
 +
* Allow the freeside user full access to the freeside database.
 +
with PostgreSQL
 
<pre>
 
<pre>
−
su bob
+
$ su - postgres
−
mkdir ~/redhat/{BUILD,RPMS,SOURCES,SPECS,SRPMS}
+
$ createuser -P freeside
 +
Enter password for user "freeside":
 +
Enter it again:
 +
Shall the new role be a superuser? (y/n) n
 +
Shall the new role be allowed to create databases? (y/n) y
 +
Shall the new role be allowed to create more new roles? (y/n) n
 +
CREATE ROLE
 
</pre>
 
</pre>
−
To build Freeside RPMs as a non-root user, your build system must have a freeside user:
+
or with MySQL:
 
<pre>
 
<pre>
−
useradd freeside
+
$ mysqladmin -u root password 'set_a_root_database_password'
 +
$ mysql -u root -p
 +
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,DROP on freeside.* TO freeside@localhost IDENTIFIED BY 'set_a_freeside_database_password';
 
</pre>
 
</pre>
−
==Create the Freeside RPMs==
+
 
−
* First, get the Freeside source code as a tarball
+
* Edit <code>/etc/freeside/secrets</code> and replace the third line (currently blank) with the password you entered in the last step.
 +
 
 +
* Add the freeside database to your database engine:
 +
with Postgres:
 
<pre>
 
<pre>
−
cd ~/redhat/SOURCES
+
$ su freeside
−
wget http://www.sisd.com/freeside/freeside-1.7.3.tar.gz
+
$ createdb -E sql_ascii freeside
 
</pre>
 
</pre>
−
(Ideally you could build the RPMs at this point using a tarbuild: rpmbuild -ta freeside.tar.gz. This doesn't work yet.)
+
or with MySQL:  
−
You can also get tarballs from CVS using ViewVC.
 
−
* Next, untar the tarball and change directory to the folder containing the RPM specfile:
 
 
<pre>
 
<pre>
−
mkdir ~/work
+
$ mysqladmin -u freeside -p create freeside  
−
cd ~/work
 
−
tar zxvf ~/redhat/SOURCES/freeside-1.7.3.tar.gz
 
−
cd freeside-1.7.3/install/rpm
 
 
</pre>
 
</pre>
−
* If you are building modified RPMs, copy your patches and supplemental files to ~/redhat/SOURCES and edit the specfile to make use of them.
+
 
−
* Next, build the RPMs:
+
* As the freeside UNIX user, run <code>freeside-setup -d your.domain.name</code> to create the database tables and initial data.
 
<pre>
 
<pre>
−
rpmbuild -ba freeside.spec
+
$ su freeside
 +
$ freeside-setup -d example.com
 
</pre>
 
</pre>
−
===About freeside-mason.deps.inc===
+
 
−
RPM attempts to automatically determine which other pieces of software, including Perl modules, the RPM it is building is dependent on.  Unfortunately, it doesn't scan Freeside's handler.pl file.  The current work-around for this is creating a file freeside-mason.deps.inc in the same folder as the RPM specfile.  If you believe the file is out of date, say because you modified handler.pl for a custom RPM, you can regenerate it with:
+
* Create the Freeside system users:  
 
<pre>
 
<pre>
−
/usr/lib/rpm/perldeps.pl -requires ../BUILD/freeside-1.7.3/htetc/handler.pl \
+
$ su freeside
−
| grep -v -E '^perl\((lib|strict|vars|RT)\)$' \
+
$ freeside-adduser -g 1 fs_queue
−
| grep -v -E '^perl\(RT::' \
+
$ freeside-adduser -g 1 fs_daily
−
| sort | uniq -u | awk '{ printf "Requires: %s\n", $1;}' > freeside-mason.deps.inc
+
$ freeside-adduser -g 1 fs_selfservice
 
</pre>
 
</pre>
−
Note that this one-liner scans the copy of handler.pl in the RPM build directory.  It also strips out references to RT.
+
 
−
==Build the RPMs for required Perl modules==
+
* Create one or more Freeside users (your internal sales/tech folks, not customer accounts):
−
Freeside uses many Perl modules, not all of which are available as RPMs. The simplest way of generating all the required RPMs is to use Ovid, which is available from CPAN, as Ovid works recursively to build RPMs of modules that the current module depends on.  Ovid also can build RPM sets from Perl bundle files.
 
−
The steps below let you build all required Perl modules as RPMs.  An alternate approach is to find a repository that contains most of these modules as RPMs and build the remainder using Ovid, cpan2rpm, or cpanflute2.
 
−
* If you have not used CPAN as the build user yet, configure CPAN:
 
 
<pre>
 
<pre>
−
su bob
+
$ su freeside
−
cpan # And answer all the prompts
+
$ freeside-adduser -g 1 username
 +
$ htpasswd /etc/freeside/htpasswd username
 +
Password:
 
</pre>
 
</pre>
−
* Install Ovid:
+
Additional users can be added using the same command or from the web interface.
−
<pre>cpan
+
 
−
install Ovid
+
* <code>/sbin/service freeside start</code>
−
quit
+
 
−
rpm -Uvh ~/redhat/RPMs/i386/ovid-0.12-1.i386.rpm
+
* <code>/sbin/service httpd restart</code>
−
</pre>
+
 
−
or
+
* Log into the web interface using the username and password you entered above.
−
<pre>
 
−
wget http://search.cpan.org/CPAN/authors/id/G/GY/GYEPI/Ovid-0.12.tar.gz
 
−
rpmbuild -ta Ovid-0.12.tar.gz
 
−
rpm -Uvh ~/redhat/RPMs/i386/ovid-0.12-1.i386.rpm
 
−
</pre>
 
−
** If you are using Ovid version 0.12, apply this patch to enable support for building Perl modules that use Module::Build instead of ExtUtils::MakeMaker:
 
−
<pre>
 
−
--- Package.pm.orig    2007-05-25 09:54:14.000000000 -0400
 
−
+++ Package.pm  2007-07-07 15:35:20.000000000 -0400
 
−
@@ -165,6 +165,7 @@
 
−
    push @out, $self->provreq($n);
 
−
  }
 
−
 
−
+  return join("\n", map { "Provides: $_"; } @out) if scalar(@out) > 5;
 
−
  return join('', 'Provides: ', join ' ', @out);
 
−
}
 
−
 
−
@@ -376,10 +377,15 @@
 
−
 
−
%install
 
−
 
−
-make PREFIX=%{_prefix} \
 
−
-    DESTDIR=%{buildroot} \
 
−
-    INSTALLDIRS=@installdirs@ \
 
−
-    install
 
−
+if [ -f Build.PL -a -f Build ] ; then
 
−
+    ./Build destdir=%{buildroot} \
 
−
+          install
 
−
+else
 
−
+    make PREFIX=%{_prefix} \
 
−
+          DESTDIR=%{buildroot} \
 
−
+          INSTALLDIRS=@installdirs@ \
 
−
+          install
 
−
+fi
 
−
 
−
[ -x /usr/lib/rpm/brp-compress ] && /usr/lib/rpm/brp-compress
 
  
−
</pre>
+
* Now proceed to the initial [[Freeside:1.7:Documentation:Administration|administration]] of your installation.
−
This is applied in /usr/lib/perl5/site_perl/5.*/Ovid:
 
−
<pre>
 
−
/bin/su -
 
−
cd /usr/lib/perl5/site_perl/5.*/Ovid
 
−
patch < Ovid.diff
 
−
</pre>
 
−
* Create bundle files for each of the Freeside RPMs:
 
−
<pre>
 
−
mkdir ~/.cpan/Bundle
 
−
install/rpm/rpm2Bundle ~/redhat/RPMS/noarch/freeside-1.7.3-1.noarch.rpm > ~/.cpan/Bundle/freeside.pm
 
−
install/rpm/rpm2Bundle ~/redhat/RPMS/noarch/freeside-mason-1.7.3-1.noarch.rpm > ~/.cpan/Bundle/freeside-mason.pm
 
−
install/rpm/rpm2Bundle ~/redhat/RPMS/noarch/freeside-postgresql-1.7.3-1.noarch.rpm > ~/.cpan/Bundle/freeside-postgresql.pm
 
−
</pre>
 
−
* Some of the modules Ovid will attempt to build use Module::Build instead of ExtUtils::MakeMaker. Ensure Module::Build is installed, for example by trying to find its files:
 
−
<pre>
 
−
locate Module/Build
 
−
</pre>
 
−
* Install Module::Build if it's not already installed (you can build it with Ovid if it is not available prebuilt):
 
−
<pre>
 
−
yum install perl-Module-Build
 
−
</pre>
 
−
* Install any prerequisites needed to build some of the modules
 
−
** GD requires header files for JPEG, PNG, and Freetype.
 
−
<pre>
 
−
yum install libjpeg-devel libpng-devel freetype-devel
 
−
</pre>
 
−
** The DBD::Pg build process also needs to know the version of PostgreSQL the module is being built for. The easiest way to do this may be to install the postgresql-devel RPM on your build machine.
 
−
* Use Ovid to create RPMs for the main Freeside dependencies:
 
−
<pre>
 
−
ovid --skip-perl-rpm-modules --packager='Yourname Here <youraddy@example.com>' \
 
−
Bundle::freeside Bundle::freeside-mason Bundle::freeside-postgresql
 
−
</pre>
 
−
* Fix up RPMs that did not build.  cpan2rpm and cpanflute2 are useful when Ovid doesn't work.
 
−
** Newer versions of DBD::Pg may require a newer version of DBI to be installed on the build computer:
 
−
<pre>
 
−
ovid --skip-perl-rpm-modules --packager='Yourname Here <youraddy@example.com>' DBI # Build DBI
 
−
/bin/su - # Get root to install the RPM
 
−
rpm -Uvh  ~bob/redhat/RPMS/i386/perl-DBI-1.601-1.i386.rpm
 
−
exit
 
−
ovid --skip-perl-rpm-modules --packager='Yourname Here <youraddy@example.com>' DBD::Pg # Try a rebuild of DBD::Pg
 
−
</pre>
 
−
** Chart has inaccurate RPM "provides" information.  This can be fixed by using Ovid to produce a specfile and then commenting out the lines that turn off AutoProvides.  Be aware that Ovid may overwrite changes when run again.
 
−
<pre>
 
−
ovid --skip-perl-rpm-modules --packager='Yourname Here <youraddy@example.com>' --nobuild Chart
 
−
vi ~/redhat/SPECS/perl-Chart.spec
 
−
rpmbuild -ba ~/redhat/SPECS/perl-Chart.spec
 
−
</pre>
 
−
** Ovid 0.12 has a bug where the version number passed to rpmbuild is incorrect for Perl modules with a trailing digit.  This affects IPC::Run3 and Crypt::PasswdMD5.  One workaround is to have Ovid create the specfile and hand-edit it before running rpmbuild yourself to build the RPMs:
 
−
<pre>
 
−
ovid --skip-perl-rpm-modules --packager='Yourname Here <youraddy@example.com>' --nobuild IPC::Run3 Crypt::PasswdMD5
 
−
cd ~/redhat/SPECS
 
−
mv perl-IPC-Run.spec perl-IPC-Run3.spec
 
−
mv perl-Crypt-PasswdMD.spec perl-Crypt-PasswdMD5.spec
 
−
vi perl-IPC-Run3.spec # Append '3' to Run where necessary
 
−
vi perl-Crypt-PasswdMD5.spec # Append '5' to MD where necessary
 
−
rpmbuild -ba perl-IPC-Run3.spec
 
−
rpmbuild -ba perl-Crypt-PasswdMD5.spec
 
−
</pre>
 
−
* Use Ovid to create RPMs for all the Freeside dependencies you require:
 
−
<pre>
 
−
ovid --skip-perl-rpm-modules --packager='Yourname Here <youraddy@example.com>' Business::OnlinePayment::AuthorizeNet</pre>
 
−
* Fix up RPMs that have inadequate dependency information.  One approach is to use Ovid to generate a specfile for the RPM, hand-edit the specfile, and then build the RPM using rpmbuild.
 
−
** The perl-GD RPM doesn't list 'gd' as one of the dependencies.
 
−
** The HTML::Mason RPM is troublesome as a lot of the dependencies are listed in the Bundle::HTML::Mason file inside the HTML::Mason tarball.  Ovid does not build all these dependencies automatically, or add them to the dependency list of the HTML::Mason RPM.
 
−
*** First, build all the dependencies:
 
−
<pre>
 
−
ovid --skip-perl-rpm-modules --packager='Yourname Here <youraddy@example.com>' Bundle::HTML::Mason
 
−
</pre>
 
−
*** Next, create the HTML::Mason specfile and hand-edit it to insert all these dependencies.  (There is no perl-Bundle-HTML-Mason RPM, so you have to list all the dependencies individually.)
 
−
*** Finally, rebuild the HTML::Mason RPM using rpmbuild.  Be aware that Ovid will overwrite your customized specfile if it thinks it needs to build HTML::Mason again.
 
−
==Create the repository==
 
−
* Copy all generated RPMs into your web server space:
 
−
<pre>
 
−
mkdir /var/www/html/fedora/7/
 
−
cp ~/redhat/RPMS/*/*.rpm /var/www/html/fedora/7
 
−
</pre>
 
−
* Remove any files that are present on any other repositories you intend to use.  (This is left as an exercise for the reader.)
 
−
* Sign all the RPMs with your GPG key:
 
−
<pre>cd /var/www/html/fedora/7
 
−
rpm --addsign *.rpm</pre>
 
−
* Download any programs needed to build the repository.  For newer, XML-based versions of yum, you'll need createrepo. If it's in a yum repository, this can be as simple as:<pre>yum install createrepo</pre>. On distros using older versions of yum (e.g. FC2 and earlier), you'll need to use yum-arch instead of createrepo to generate the repository metadata. yum-arch should be installed as part of the yum RPM, so there's no need to install another RPM.
 
−
* Create the repository:
 
−
<pre>createrepo /var/www/html/fedora/7
 
−
</pre>
 
−
* Make sure the web server is started
 
−
At this point your web server is acting as a yum repository with a URL of http://localhost/fedora/7/
 
−
* Create a file defining the repository in /etc/yum.repos.d/freeside.repo, or put it up on your web server so it can be downloaded to machines that Freeside will be installed on.
 
−
<pre>
 
−
#Packages used in Freeside
 
−
[freeside]
 
−
name=Freeside-$releasever
 
−
#mirrorlist=http://localhost/mirrors/fedora/$releasever/$basearch
 
−
baseurl=http://localhost/fedora/$releasever/
 
−
gpgcheck=1
 
−
enabled=0
 
−
gpgkey=http://localhost/RPM-GPG-KEY-yourname
 
−
</pre>
 
−
Once this file is installed in /etc/yum.repos.d, you can proceed to [[#yum|install Freeside from the repository]].
 
  
 
=Upgrading=
 
=Upgrading=
Line 273: Line 259:
 
==Introduction==
 
==Introduction==
 
If you have an existing Freeside installation that was installed from the tarball, following the instructions for installing or upgrading from RPM&nbsp;'''''may''''' result in an operational system where the RPMs have overwritten most or all of the files installed from the tarball or CPAN.
 
If you have an existing Freeside installation that was installed from the tarball, following the instructions for installing or upgrading from RPM&nbsp;'''''may''''' result in an operational system where the RPMs have overwritten most or all of the files installed from the tarball or CPAN.
−
==Upgrading using RPM==
+
 
−
When there's a new version of Freeside available as RPM, just download the new RPMs and upgrade them:<pre>
+
==Upgrading==
−
rpm -Uvh --test freeside-1.7.3-1.noarch.rpm freeside-mason-1.7.3-1.noarch.rpm freeside-postgresql-1.7.3-1.noarch.rpm
+
Upgrading can be done with a tool such as YUM or APT (or up2date on RHEL), preferably, or as a last resort, with RPM directly.
−
</pre>
+
 
−
==Upgrading using a repository==
+
===Upgrading using a repository===
 
If you installed the RPM version of Freeside from a repository, and a new version is available on the repository, then you can install the new files on your system using the package manager:
 
If you installed the RPM version of Freeside from a repository, and a new version is available on the repository, then you can install the new files on your system using the package manager:
 
<pre>yum update</pre>
 
<pre>yum update</pre>
Line 283: Line 269:
 
<pre>apt-get update</pre>
 
<pre>apt-get update</pre>
 
To avoid unplanned upgrades, you may wish to mark the repository containing Freeside as disabled, or remove it from your yum or apt configuration files.
 
To avoid unplanned upgrades, you may wish to mark the repository containing Freeside as disabled, or remove it from your yum or apt configuration files.
−
==Finalizing the upgrade using freeside-install==
+
===Upgrading using RPM===
−
This will not perform any database upgrades, so you should refer to the tarball upgrade documentation and do any database changes by hand. (A future version of [[#freeside-install|freeside-install]] may be able to perform the database changes needed in an upgrade.)
+
When there's a new version of Freeside available as RPM, just download the new RPMs and upgrade them:<pre>
 +
rpm -Uvh --test freeside-1.7.3-1.noarch.rpm freeside-mason-1.7.3-1.noarch.rpm freeside-postgresql-1.7.3-1.noarch.rpm
 +
</pre>
 +
 
 +
==Finalizing the upgrade==
 +
* As the freeside UNIX user, run <code>freeside-upgrade username</code>, passing the username of an internal Freeside user.
 +
* If freeside-upgrade hangs, try stopping Apache, all Freeside processes, and anything else connected to your database, especially on older PostgreSQL versions.
 +
* Restart Apache and Freeside:
 +
  /etc/init.d/httpd restart
 +
  /etc/init.d/freeside restart
 +
* You may want to check your ACLs under Configuration->Employee->View/Edit employee groups and grant some of the new rights to one or more groups.
 +
 
 +
=Known issues=
 +
 
 +
* yum will not automatically upgrade Perl modules bundled in the main Perl RPM to the newer versions on the Freeside repository due to the lack of version information in the main Perl RPM.  (It cannot determine that the newer versions are newer.)  So, you have to install them as a separate operation.  This applies to the <code>perl-File-Temp perl-CGI.pm perl-Test-Simple</code> RPMs.
 +
 
 +
* ssh -X in as root and run system-config-securitylevel (can't seem to do this from -tui. may need to <code>yum install xauth xorg-x11-fonts-*</code>)
 +
** firewall options, open up www and secure www
 +
** selinux options: enforcing -> permissive (otherwise freeside can't even create /etc/freeside/masondata/obj etc.)

Latest revision as of 18:17, 19 December 2011

Introduction

Warning!

The RPM 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 RPM installation if you are prepared to work around omissions and inaccuracies, and can recover data in the event of a loss.

Information

The currently available packages are for the i386 and x86_64 architectures. The packages are built on CentOS 5 and currently tested on CentOS and RHEL 5. Packages for CentOS/RHEL 4 are no longer available.

Packagers for other distributions are welcome; see creating RPM repositories. You can also read about our own RPM build system.

Installing the RPM 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.

Status

The RPM version of Freeside does not include Request Tracker at this time. The self-service RPM has not been fully tested. Both PostgreSQL and MySQL back-end databases should work. The version and release of the RPM were shown in the "Billing Main" page in Freeside, but we concluded this was misleading. You can now get the version and release by entering rpm -q freeside at the command line.

Installation

RPM installation can preferably be done with a tool such as YUM or APT (or up2date on RHEL). As a last resort, you can install with RPM directly.

Installing using yum

Setup YUM

  • If you are installing to a machine behind a proxy server, you may need to set up the proxy directives in /etc/yum.conf for yum to work correctly.
  • Make sure the yum priorities plugin is installed by running yum install yum-plugin-priorities for CentOS v4, or yum install yum-priorities for CentOS v5.
  • Make sure the yum priorities plugin is enabled by editing the /etc/yum/pluginconf.d/priorities.conf file, and ensuring that it contains the following lines: 
 [main]
 enabled=1
  • Edit /etc/yum.repso.d/CentOS-Base.repo, adding the following lines to the [base] and [update] sections, and adding the [centosplus] section:
[base] 
exclude=php* httpd* MySQL* mysql* perl perl-suidperl unixODBC* mod_auth_mysql mod_auth_pgsql mod_perl mod_perl-devel mod_ssl
priority=1

[update]
exclude=php* httpd* MySQL* mysql* perl perl-suidperl unixODBC* mod_auth_mysql mod_auth_pgsql mod_perl mod_perl-devel mod_ssl
priority=1

[centosplus]
enabled=1
priority=2
  • Select a repository containing the required RPMs, and add the repository to a new file in your /etc/yum.repo.d directory or directly to the /etc/yum.conf file. If no such repository exists, you can create your own.

1.7 pre-release repository

This repository contains only the Freeside RPMs for release candidates. Use the testing repository for all of the required Perl RPMs. 

cd /etc/yum.repos.d
wget http://www.freeside.biz/~rsiddall/freeside.repo

The repository definition file defines a testing, stable, and a pre-release repository. All of these are disabled by default, so you either need to include --enablerepo=freeside-testing --enablerepo=freeside-prerelease when invoking yum, or just edit the file and enable the repositories you want to use by changing the enable=0 to enable=1 in the corresponding section of the file.

Since the release candidate RPMs have a higher version number than the CVS snapshot builds, yum will install the release candidates instead of the CVS snapshot. You can verify this after yum completes by entering rpm -q freeside and checking that it's something like freeside-1.7.4rc2-1.

1.7 stable repository

Follow the instructions for the 1.7 pre-release repository, but enable the stable repository instead of the pre-release.

1_7_BRANCH repository

CentOS/RHEL v5 i386: 
#Packages used in Freeside
[freeside]
name=Freeside-5
baseurl=http://www.freeside.biz/~ivan/repo/centos/5/freeside-1.7/testing/i386
gpgcheck=1
enabled=1
priority=2
gpgkey=http://www.freeside.biz/~rsiddall/RPM-GPG-KEY-Freeside
CentOS/RHEL v5 x86_64: 
#Packages used in Freeside
[freeside]
name=Freeside-5
baseurl=http://www.freeside.biz/~ivan/repo/centos/5/freeside-1.7/testing/x86_64
gpgcheck=1
enabled=1
priority=2
gpgkey=http://www.freeside.biz/~rsiddall/RPM-GPG-KEY-Freeside

Install

  • Install the required components by issuing the commands:
yum install httpd mod_perl mod_ssl perl postgresql-server
yum install perl-File-Temp perl-CGI.pm
yum install freeside freeside-mason freeside-postgresql perl-Business-OnlinePayment-AuthorizeNet

with these changes:

  • Replace posgresql with mysql if you wish to use MySQL instead of PostgreSQL for the main Freeside database.
  • Replace AuthorizeNet with the name of the Business::OnlinePaymet module for the credit card gateway you wish to use.
  • Add the RPM name of any additional Business::OnlinePayment gateways you wish to install.

At this point all the required components should be installed and the freeside user account created. You can now complete the installation.

Troubleshooting

  • If you are using a repository that is normally disabled, use yum --enablerepo=Freeside-4 install ... where Freeside-4 is the name of the repository.
  • If you get an error such as:
Transaction Check Error:   file /usr/share/man/man3/File::Temp.3pm.gz from install of perl-File-Temp-0.18-1 conflicts with file from package perl-5.8.8-4.el4s1

then you're using an operating system with a badly packaged Perl. You will have to force the installation of the RPM which conflicts with the Perl, using something like: 

rpm -Uvh --force /var/cache/yum/freeside/packages/perl-File-Temp-0.18-1.x86_64.rpm

This installs the conflicting RPM from yum's cache for the "freeside" repository. You can then retry installing from yum.

Installing using up2date

Mainly for vanilla RHEL 4; if you are running RHEL 5 or CentOS, the yum or apt-get instructions may be preferable.

Setup up2date

  • Import GPG keys:
 rpm --import http://mirror.centos.org/centos/RPM-GPG-KEY-CentOS-5
 rpm --import http://www.freeside.biz/~rsiddall/RPM-GPG-KEY-Freeside
  • Select a repository containing the required RPMs and add the repository to your /etc/sysconfig/rhn/sources file. If no such repository exists, you can create your own.

1_7_BRANCH repository

RHEL v5 i386: 
yum centosplus http://mirror.centos.org/centos/4/centosplus/i386/
yum freeside http://www.freeside.biz/~ivan/repo/centos/4/freeside-1.7/testing/i386
RHEL v5 x86_64: 
yum centosplus http://mirror.centos.org/centos/4/centosplus/x86_64/
yum freeside http://www.freeside.biz/~ivan/repo/centos/4/freeside-1.7/testing/x86_64

Install

  • Install the required components by issuing the commands:
up2date httpd mod_perl mod_ssl perl postgresql-server tetex-latex perl-Digest-SHA1 perl-XML-Parser
up2date perl-File-Temp #this will fail, that's okay for now
rpm -Uvh --force /var/spool/up2date/perl-File-Temp-0.18-1.x86_64.rpm #to force File::Temp 0.18 installation, for now
up2date freeside freeside-mason freeside-postgresql perl-Business-OnlinePayment-AuthorizeNet

with these changes:

  • Replace posgresql with mysql if you wish to use MySQL instead of PostgreSQL for the main Freeside database.
  • Replace AuthorizeNet with the name of the Business::OnlinePaymet module for the credit card gateway you wish to use.
  • Add the RPM name of any additional Business::OnlinePayment gateways you wish to install.

At this point all the required components should be installed and the freeside user account created. You can now complete the installation.

Troubleshooting

  • Does up2date show a "freeside" channel when doing up2date --show-channels, but won't install packages from that repository? Make sure /etc/sysconfig/rhn/up2date has a line designating a blank proxy:
 httpProxy=

Installing using APT

Setup APT

Select a repository containing the required RPMs and add the repository to your /etc/apt.conf file.. If no such repository exists, you can create your own.

1.7.3 stable repository

(not yet available)

1_7_BRANCH testing repository

(not yet available)

Install

  • Install the required components by issuing the command:
apt-get install freeside freeside-mason freeside-postgresql perl-Business-OnlinePayment-AuthorizeNet

with these changes:

  • Replace posgresql with mysql if you wish to use MySQL instead of PostgreSQL for the main Freeside database.
  • Replace AuthorizeNet with the name of the Business::OnlinePaymet module for the credit card gateway you wish to use.
  • Add the RPM name of any additional Business::OnlinePayment gateways you wish to install.

At this point all the required components should be installed and the freeside user account created. You can now complete the installation.

Installation using RPM

Installation is much easier if you have a repository that works with a tool such as yum, apt-get or up2date. If you only have rpm and wish to use that, enter: 

rpm -Uvh --test freeside-1.7.3-1.noarch.rpm \
freeside-mason-1.7.3-1.noarch.rpm \
freeside-postgresql-1.7.3-1.noarch.rpm \
perl-Business-OnlinePayment-AuthorizeNet-3.17-1.i386.rpm

Where:

  • 1.7.3-1 is the version of Freeside and the release of the RPM. Change this if necessary.
  • postgresql is the database you wish to use as the Freeside back-end. Replace freeside-postgresql with freeside-mysql if you wish to use MySQL. See the main installation document for which databases are supported.
  • Replace AuthorizeNet with the name of the credit card processor you wish to use for real-time transactions. Also replace 3.17-1.i386 with the current version, release, and architecture of the corresponding Business::OnlinePayment RPM.

The command should result in some warnings about unsatisfied dependencies. Find the corresponding RPMs and add them to the list on the command line. Keep doing this until the command results in no warnings, then issue the command one last time without the --test to actually install all the RPMs.

At this point all the required components should be installed and the freeside user account created. You can now complete the installation.

Finalizing the installation

  • Start the database:

with PostgreSQL 

 chown -R postgres:postgres /var/lib/pgsql
 /sbin/service postgresql start

or with MySQL 

 /sbin/service mysqld start
  • Allow the freeside user full access to the freeside database.

with PostgreSQL 

$ su - postgres
$ createuser -P freeside
Enter password for user "freeside": 
Enter it again: 
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n
CREATE ROLE

or with MySQL: 

$ mysqladmin -u root password 'set_a_root_database_password'
$ mysql -u root -p
mysql> GRANT SELECT,INSERT,UPDATE,DELETE,INDEX,ALTER,CREATE,DROP on freeside.* TO freeside@localhost IDENTIFIED BY 'set_a_freeside_database_password';
  • Edit /etc/freeside/secrets and replace the third line (currently blank) with the password you entered in the last step.
  • Add the freeside database to your database engine:

with Postgres: 

$ su freeside
$ createdb -E sql_ascii freeside

or with MySQL: 

$ mysqladmin -u freeside -p create freeside
  • As the freeside UNIX user, run freeside-setup -d your.domain.name to create the database tables and initial data.
$ su freeside
$ freeside-setup -d example.com
  • Create the Freeside system users: 
$ su freeside
$ freeside-adduser -g 1 fs_queue
$ freeside-adduser -g 1 fs_daily
$ freeside-adduser -g 1 fs_selfservice
  • Create one or more Freeside users (your internal sales/tech folks, not customer accounts):
$ su freeside
$ freeside-adduser -g 1 username
$ htpasswd /etc/freeside/htpasswd username
Password:

Additional users can be added using the same command or from the web interface.

  • /sbin/service freeside start
  • /sbin/service httpd restart
  • Log into the web interface using the username and password you entered above.

Upgrading

Introduction

If you have an existing Freeside installation that was installed from the tarball, following the instructions for installing or upgrading from RPM may result in an operational system where the RPMs have overwritten most or all of the files installed from the tarball or CPAN.

Upgrading

Upgrading can be done with a tool such as YUM or APT (or up2date on RHEL), preferably, or as a last resort, with RPM directly.

Upgrading using a repository

If you installed the RPM version of Freeside from a repository, and a new version is available on the repository, then you can install the new files on your system using the package manager: 

yum update

or: 

apt-get update

To avoid unplanned upgrades, you may wish to mark the repository containing Freeside as disabled, or remove it from your yum or apt configuration files.

Upgrading using RPM

When there's a new version of Freeside available as RPM, just download the new RPMs and upgrade them:
rpm -Uvh --test freeside-1.7.3-1.noarch.rpm freeside-mason-1.7.3-1.noarch.rpm freeside-postgresql-1.7.3-1.noarch.rpm

Finalizing the upgrade

  • As the freeside UNIX user, run freeside-upgrade username, passing the username of an internal Freeside user.
  • If freeside-upgrade hangs, try stopping Apache, all Freeside processes, and anything else connected to your database, especially on older PostgreSQL versions.
  • Restart Apache and Freeside:
 /etc/init.d/httpd restart
 /etc/init.d/freeside restart
  • You may want to check your ACLs under Configuration->Employee->View/Edit employee groups and grant some of the new rights to one or more groups.

Known issues

  • yum will not automatically upgrade Perl modules bundled in the main Perl RPM to the newer versions on the Freeside repository due to the lack of version information in the main Perl RPM. (It cannot determine that the newer versions are newer.) So, you have to install them as a separate operation. This applies to the perl-File-Temp perl-CGI.pm perl-Test-Simple RPMs.
  • ssh -X in as root and run system-config-securitylevel (can't seem to do this from -tui. may need to yum install xauth xorg-x11-fonts-*)
    • firewall options, open up www and secure www
    • selinux options: enforcing -> permissive (otherwise freeside can't even create /etc/freeside/masondata/obj etc.)
Retrieved from "http://freeside.biz/mediawiki/index.php?title=Freeside:1.7:Documentation:InstallingUsingRPM&oldid=6797"