ABS Manual Installation Guide

Thisdocumentincludesalltheinformationrequiredtoinstall,upgradeandconfiguretheAmberdmsBillingSystemmanuallyonnon
officallysupportedplatforms.
IfyouareauserofRHEL,CentOSorFedora,youshouldinsteadrefertooursupportedplatformsinstallationguidesincetheinstall
pathisconsiderablyeasier.
Copyright2010AmberdmsLtd
Thisdocumentmaybefreelydistributedbutmodificationsarenotpermitted.

Version8March2010

ABSManualInstallationGuide

TableofContents
1.Introduction............................................................................................................................................................................................3
2.ApplicationRequirements......................................................................................................................................................................4
2.1.OperatingSystem...........................................................................................................................................................................4
2.2.OSSecurityFeatures.....................................................................................................................................................................4
2.3.PHPVersions.................................................................................................................................................................................4
2.3.1.Olderthan4.3.0.....................................................................................................................................................................4
2.3.2.PHPversion>4.3.0..............................................................................................................................................................5
2.3.3.PHPversion5.0.0>5.2.0....................................................................................................................................................5
2.3.4.PHPversion5.2.0+...............................................................................................................................................................5
2.4.PHPModules.................................................................................................................................................................................5
2.4.1.RequiredModules.................................................................................................................................................................5
2.4.2.OptionalModules..................................................................................................................................................................5
2.5.AdditionalRequirements...............................................................................................................................................................5
2.5.1.MySQLServer......................................................................................................................................................................5
2.5.2.PDFLatex(optional).............................................................................................................................................................6
3.ImportantNotices...................................................................................................................................................................................7
3.1.AvoidSharedHosting....................................................................................................................................................................7
3.2.PhoneHomeDisclaimer................................................................................................................................................................7
4.InstallationInstructions..........................................................................................................................................................................8
4.1.DownloadTarball..........................................................................................................................................................................8
4.2.ApplicationInstallation.................................................................................................................................................................8
4.3.DatabaseInstallation......................................................................................................................................................................9
4.3.1.AutomatedUtility.................................................................................................................................................................9
4.3.2.ManualInstallation...............................................................................................................................................................9
4.4.ApacheConfiguration..................................................................................................................................................................10
4.5.SELinux(optional)......................................................................................................................................................................10
4.5.1.DisablingSELinux..............................................................................................................................................................10
4.5.2.WritingSELinuxPolicies...................................................................................................................................................10
4.6.AccesstheBillingSystem...........................................................................................................................................................10
5.UpgradeInstructions............................................................................................................................................................................12
5.1.Backingupthedatabase..............................................................................................................................................................12
5.2.Upgradingtheapplications..........................................................................................................................................................12
5.3.Upgradingthedatabase................................................................................................................................................................13

Copyright2010AmberdmsLtd

Page2/13

ABSManualInstallationGuide

1. Introduction
TheAmberdmsBillingSystemisapowerful,userfriendly,opensourcebillingsystemdesignedforsmallandmediumbusinessesand
isfullyopensourceundertheGNUAGPLsoftwarelicense.
ThisguidedetailsthestepstoinstalltheAmberdmsBillingSystemontoyourownserverswhenrunninganonsupported
operatingsystem.
Amberdmsprovidesofficialsupportforanumberofdistributions,ifyouarerunninganyofthem,pleasereadtheABSSupportedOS
InstallGuidedocumentationinstead:
1.
2.
3.

RHELversions4and5
CentOSversions4and5
Fedoraversions11and12

Ifyourplatformisnotlistedabovethenyouarerunningonanunsupportedplatformandthisisthecorrectdocumentforyou.
Notethatwhilstanythingnotlistedaboveisanunsupportedplatform,thissimplymeansthatAmberdmswon'tprovidesupportfor
issuesexperiencedontheseplatforms,howeverintypicaloperation,ABSwillworkfineonmostLinuxandunixlikeoperating
systems.
Ifyouarelookingforuserdocumentationordeveloperinformation,checkoutthefulllistofmanualsonlineat:
http://www.amberdms.com/?cms=opensource_billing_download

Copyright2010AmberdmsLtd

Page3/13

ABSManualInstallationGuide

2. ApplicationRequirements
TheAmberdmsBillingSystemisalargeapplicationwithmanyfeatures.Theinformationinthissectionofthedocumentdetailsall
thecomponentsthatitrequires.

2.1. OperatingSystem
TheAmberdmsBillingSystemhasbeenreportedbyuserstoworkon:

Debian

Ubuntu

MacOSLeopard
Withtherightpackageinstalls,itshouldalsoworkon:

Solaris/OpenSolaris

FreeBSD/OpenBSD/NetBSD

AnyotherreasonablystandardLinuxdistribution.
Itisunlikelythatitwilloperatecorrecton:

MicrosoftWindowsThebaseoftheapplicationshouldwork,butfeaturessuchasemailsorPDFgeneratearelikelytofail
duetodependenceonnixstylefilesystemstructuresandapplications.
Ifyouwishtogainofficialsupportforaparticularoperatingsystem/distribution,Amberdmsisalwaysinterestedinperforming
fundeddevelopmentoracceptingcontributionsemailsupport@amberdms.comifyouareinterestedtodiscussfurther.

2.2. OSSecurityFeatures
SomeoperatingsystemssuchasLinuxnowincludesecurityfeaturessuchasSELinux,SMACKorAppArmor.Thesefeaturescan
ofteninterferewiththeAmberdmsBillingSystem,sinceABSrequiresaccesstofeaturenormallyforbiddensuchasGNUtar,
pdflatexandothers.
Inparticular,thetwomostcommonfeaturesthatgetblockedbyOSsecurityfeaturesare:

ExecuteGNUtar
ExecutePDFLatex/TeTex/Texlivethiscanbecomplex,sinceitalsoneedspermissiontoallthefontsforTex.

ThisdocumentincludesinformationonhowtoadjustthepoliciesordisableSELinux,howeverusersofothersecurityfeatureswill
eitherneedtolearnhowtoadjusttheirpoliciesordisablethem.

2.3. PHPVersions
AmberdmsrecommendsrunningthisapplicationwithPHPversions5.2.0andhigherinordertoreceivethefullfeaturesetofthe
application.ItispossibletorunthisproductwitholderPHPreleases,butsomefeatureswillnotbeavailable.
WehavealistofPHPversionsbelowandwhatissupportedwitheachspecificrelease:

2.3.1.

OLDERTHAN4.3.0

ThereisnosupportforversionsofPHPolderthan4.3.0.Ifyoudouseitwithanolderrelease,themajoritymayworkOK,
butyoucouldexperienceunexpectedandundesirablebehaviour.

Copyright2010AmberdmsLtd

Page4/13

ABSManualInstallationGuide

2.3.2.

PHPVERSION>4.3.0

UnderPHP4allfeaturesexceptthefollowingaresupported:
1.

Userspecifictimezonesarenotsupported.Allusersarelimitedtousingthedefaultservertimezone.

2.

TheSOAPAPIisnotsupported.

2.3.3.

PHPVERSION5.0.0>5.2.0

UnderPHP5uptill5.2.0,allthefeaturesexceptthefollowingaresupported:
1.

2.3.4.

Userspecifictimezonesarenotsupported.Allusersarelimitedtousingthedefaultservertimezone.

PHPVERSION5.2.0+

UnderPHP5.2.0andabove,allfeatureoftheAmberdmsBillingSystemarefullysupported.

2.4. PHPModules
2.4.1.

REQUIREDMODULES

PHPisaverymodularplatformandoftendistributionssplititupintomultiplepackages.TheAmberdmsBillingSystem
requiresthefollowingcomponentsaswellasthecoreofPHPitself:
1.
2.
3.

phpcurl
phpmysql
phppear

IfyouinstallPHPyourselffromsource,makesureyouhaveusedtheappropriateconfigureoptionstoincludethesemodules
whenbuilding.

2.4.2.

OPTIONALMODULES

Optionalmodulesareneededtoenablespecificfeatures,howeverthebaseapplicationwilloperatewithoutthem.
ThefollowingmodulesarerequiredforPHPtoallowgenerationofemailsbytheAmberdmsBillingSystem:
1. PHPMailModule
2. PHPMail:MimeModule
Bothofthesemodulescanbedownloadedbypearortheymaybealreadyincludedinyourdistributionsrepository.

2.5. AdditionalRequirements
Thefollowingotherapplicationsarerequired:

2.5.1.

MYSQLSERVER

TheAmberdmsBillingSystemrequiredMySQLserverversion4orabovewithInnoDBsupportenabled.

Copyright2010AmberdmsLtd

Page5/13

ABSManualInstallationGuide

2.5.2.

PDFLATEX(OPTIONAL)

InordertobeabletogeneratePDFversionsofinvoicesandreports,pdflatexmustbeinstalledalongwithit'sfontpackages.
ItispossibletoruntheAmberdmsBillingSystemwithoutthisprogram,butPDFgenerationwillnotwork.
Dependingonthedistributionyouareusing,youcanfindpdflatexintheoldertetexpackagesorit'ssuccessor,texlive.
Debianuserswillneedtoinstalltexlivelatexrecommendedandtexlivelatexbasepackages.

Copyright2010AmberdmsLtd

Page6/13

ABSManualInstallationGuide

3. ImportantNotices
3.1. AvoidSharedHosting
Theinstallinstructionsinthisdocumentaredesignedforusersrunningtheirownserversorvirtualmachinesandassumesrootaccess
tothesystemwithprivilegestoinstallpackagesasdesiredaswellassecuritypolicies.
AmberdmsdoesnotrecommendorsupportinstallingonSharedHostingproviders,theseprovidersoftenhaverestrictedPHP's
featuresandpreventinstallationofcomponentssuchaspdflatexorSELinuxpoliciescausingundesirableandbrokenapplication
behaviour.
Ifyouwishtoavoidthecostofavirtualmachineordedicatedserver,considersigningupforAmberdms'shostedplatforminstead,
thiswillprovidealowcostandreliable,managedplatform.Formoredetails,pleasevisitwww.amberdms.com/billingoremail
[email protected]

3.2. PhoneHomeDisclaimer
Beforeinstalling,pleasebeawarethattheAmberdmsBillingSystemincludesaphonehomefeature,usedtosendbackafewdetails
toAmberdmssothatwecanbetterworkouttheneedsandrequirementsofouruserbase.
Thisinformationisanonymousandisonlyusedsothatwecanprovidebetterservicesandmakebetterdevelopmentdecisionstomeet
theneedsofouruserbase.
Webelieveinopennessandprivacy,sobelowisalistofalltheinformationthatgetssenttoAmberdms:
InformationSent

Whatweuseitfor

AmberdmsBillingSystemversion

Toseehowquicklyusersupdateandifolderversionsremaininuseforsignificanttime.

OSandwebserverversion.

Allowsustodecidewhatplatformstoofficiallysupportandmakepackagingtoolsfor
easierdeploymentforourusers.

1.

PHPversion

ByknowingthecommonversionsofPHPused,wecanmakelogicaldecisionsonwhat
versionstotestwithandhowlongtosupportolderreleasesfor.

2.

SubscriptionID

Usedtodifferentiatebetweenourpaidandopensourcecustomers.

Infuture,thisfeaturewillbeextendedtocheckforupdatesaswell,toinformadministratorswhenthereisanewversionofthe
softwareavailable(withsecurityorbugfixes).
Ifyouwishtodisablethephonehomefeature,youcandosoonceinstalled,bylogginginasanadministrator,goingtothecontrol
panelandthendisablingthePHONE_HOMEoption(althoughitmeansalottousifyoudidn't).
IfyouhaveanyconcernsregardingthisfeatureandAmberdms'scommitmenttoprivacy,pleasefeelwelcometoemail
[email protected].

Copyright2010AmberdmsLtd

Page7/13

ABSManualInstallationGuide

4. InstallationInstructions
Beforebeginninginstallation,pleasemakesureyouhavesatisfiedallrequirementsasperSection2:ApplicationRequirements
above.
Theseinstructionsassumethefollowing:

Applicationinstallpathto/usr/share/amberdms/billing_system/

Configurationinstallpathto/etc/amberdms/billing_system/
Itispossibletodeploytootherlocations,youjustneedtosubstitutethepathsintheinstallinstructionsbelowtothoseyoudesire.

4.1. DownloadTarball
Firstdownloadthelatestsourcetarballfromhttp://www.amberdms.com/?cms=opensource_billing_download
Notethatyoudonotneedtheextrastarballunlessyouareplanningtododevelopmentworkandwantthesamplecodeforintegrating
withtheSOAPAPIorsomeofthebetatools.

4.2. ApplicationInstallation
Firstcopythedownloadtarballto/tmpandunpackwith:
$tarxkjvfamberdmsbsVERSION.tar.bz2
Createrequireddirectories
$mkdirp/usr/share/amberdms
$mkdirp/etc/amberdms/billing_system
Copythetarball'sunpackeddirectory:
$cpvramberdmsbsVERSION/usr/share/amberdms/billing_system
Installtemplateconfigurationfile
$cp/usr/share/amberdms/billing_system/include/sample_config.php/etc/amberdms/billing_system/config.php
$lns/etc/amberdms/billing_system/config.php/usr/share/amberdms/billing_system/include/configsettings.php
Installcronfile
$cp/usr/share/amberdms/billing_system/help/resources/amberdmsbscron/etc/cron.d/amberdmsbs
Setpermissionsthisisimportant,sinceweneedtolimitwhatuserscanreadfilessuchasconfiguration.Theapacheusercanbe
nameddifferentlyonsomesystems,typicallyApacheisrunaseither:

wwwdata(DebianandUbuntu)

apache

apache2

httpd
Ifyouareunsure,checktheUsersettingsintheApacheconfigurationfiles.Fortheseinstructionsweassumeapacheforthe
webserverandcronforthecrondaemon.
$chownRroot:apache/etc/amberdms/billing_system
$chmodR750/etc/amberdms/billing_system
$chmodR644/etc/cron.d/amberdmsbs
$chmodR755/usr/share/amberdms/billing_system
Thiscompletesinstallationoftheapplicationfiles,nowmoveontothedatabaseinstallation.

Copyright2010AmberdmsLtd

Page8/13

ABSManualInstallationGuide

4.3. DatabaseInstallation
Databaseinstallationcanbedoneinoneoftwowayseitherviatheautomatedutility(recommended)ormanuallybyimportingthe
rightschemafile.
BeforeinstallingtheABSdatabase,ifyouhaveonlyjustinstalledMySQL,youshouldsetarootpasswordforsecurity.Toconfigure
arootpassword,runthefollowingcommands:
$ /usr/bin/mysqladmin -u root password 'NEWPASSWORD' -p
$ /usr/bin/mysqladmin -u root -h $HOSTNAME password 'NEWPASSWORD'

4.3.1.

AUTOMATEDUTILITY

Amberdmshasdevelopedautilitywhichwillimportatemplatedatabase,createaMySQLuseraccountfortheDBonlyand
automaticallywritestheconfigurationfilefortheuser.
Pleasenote:thistoolisdependantonthedefaultpathsfortheinstallofABS,ifyouareinstallingtoacustompath
location,youshouldfollowthemanualDBinstructions.
Toruntheinstallationtool,execute:
$ cd /usr/share/amberdms/billing_system/help/resources/; ./autoinstall.pl
Ifyouexperienceanyproblems,followthroughwiththemanualinstallstepsbelowinstead.

4.3.2.

MANUALINSTALLATION

TheAmberdmsBillingSystemdatabasecanbeimportedmanuallybyfollowingthesesteps:
1.

Locatethelatestversionof/usr/share/amberdms/billing_system/help/schmea/version_*_install.sql

2.

Importwith:
$mysqlurootp</usr/share/amberdms/billing_system/help/schmea/version_LATESTDATE_install.sql

3.

CreateaMySQLuseracountforthebillingsystemonly:
$mysqlurootp
GRANTUSAGEON*.*TO'billing_system@'%'IDENTIFIEDBY'passwordgoeshere'WITH
MAX_QUERIES_PER_HOUR0MAX_CONNECTIONS_PER_HOUR0MAX_UPDATES_PER_HOUR0;
GRANTSELECT,INSERT,UPDATE,DELETE,CREATE,DROP,INDEX,ALTER,CREATE
TEMPORARYTABLES,LOCKTABLESON`billing_system`.*TO'billing_system'\@'%';\n";
\q

4.

Updatetheconfigurationfilein/etc/amberdms/billing_system/config.phpwiththecorrectDBnameanduser
settings.

Copyright2010AmberdmsLtd

Page9/13

ABSManualInstallationGuide

4.4. ApacheConfiguration
Afterfollowingstepsabove,themainapplicationconfigurationfilewillhavebeenwrittenwiththecorrectMySQLdatabase
configuration.
Theremainingstepistocreateanapacheconfigurationfiletheexactlocationwillvarydependingonthestructureoftheapache
configuration,butlookforconf.d/orsomeothermoduleconfigurationdirectory.
Createaconfigurationfilewith:
cat>amberdmsbs.conf<<"EOF"
#
#AmberdmsBillingSystemisanopensourceaccounting,servicebillingandtimekeepingwebapplication.
#
Alias/billing_system/usr/share/amberdms/billing_system
<Location/billing_system>
Orderdeny,allow
Allowfromall
AllowOverrideall
</Location>
EOF
Thenreloadapachewith:
$apachectlkrestart

4.5. SELinux(optional)
IfyouroperatingsystemrunsSELinux,youneedtoeitherdisableSELinuxorupdateyourpoliciestopermitcorrectoperationof
ABS.TypicallySELinuxwillbreakpdflatexPDFgenerationanddatabasebackup/exports.

4.5.1.

DISABLINGSELINUX

YoucandisableSELinuxbyrunning:
$setenforcepermissive
Andthenupdate/etc/selinux/configandchangingthepolicyfromTargettedtoEnforcingtomakethechange
permanently.

4.5.2.

WRITINGSELINUXPOLICIES

WritingSELinuxpoliciesrequiressolidunderstandingofhowSELinuxworks,butmoderndistributionsdomakeiteasier.
Inshort,youneedto:
1. SwitchSELinuxtopermisivemode
2. RunallthefeaturesthatSELinuxisbreaking,tocaptureauditloginformation.
3. Runaudit2allowtogeneratepolicy.
4. Compilethatpolicyintoamoduleforloadingorincludeintothesystembasepolicy.
Theexactstepswilldifferdependingonyourplatform,agoodresourceforinformationonwritingSELinuxpolicies,seethe
CentOS5manualathttp://www.centos.org/docs/5/html/Deployment_GuideenUS/secselbuildingpolicymodule.html

4.6. AccesstheBillingSystem
TheAmberdmsBillingSystemisnowinstalledtobeginusingit,useyourwebbrowsertoaccess:
Copyright2010AmberdmsLtd

Page10/13

ABSManualInstallationGuide

https://example.com/billing_system
(whereexample.comisthehostnameofyourserver)
Thedefaultloginaccountis:
Username:
setup
Password:
setup123
Onceloggedin,youcanchangeyourpasswordusingtheoptionspage.
Forfurtherinformation,includinginformationonconfiguringprogramoptions,pleasereadtheAmberdmsBillingSystem
UserGuide.

Copyright2010AmberdmsLtd

Page11/13

ABSManualInstallationGuide

5. UpgradeInstructions
UpgradingtheAmberdmsBillingSystemisreasonablystraightforwards,replacetheapplicationfileswiththelatestrelease,runthe
MySQLDBupdatescriptandalldone.
Youcanskipanynumberofversionswhenupgradingandtheschemaupdatescriptwillhandlethatcorrectly.
Beforebeginningtheupgrade,pleasemakesureyouhavesatisfiedallrequirementsasperSection2:ApplicationRequirements
above,thedependenciescansometimeschangebetweenreleases.
Theseinstructionsassumethefollowing:

Applicationinstallpathto/usr/share/amberdms/billing_system/

Configurationinstallpathto/etc/amberdms/billing_system/
Itispossibletodeploytootherlocations,youjustneedtosubstitutethepathsintheinstallinstructionsbelowtothoseyoudesire.

5.1. Backingupthedatabase
Beforedoinganything,firstbackupthedatabase.YoucandothisusingtheCLImysqldumptools,orbyloggingintotheAmberdms
BillingSystemasanadministratorandgoingAdmin>DatabaseBackup.

5.2. Upgradingtheapplications
Upgradingtheapplicationinvolvesreplacingthesourcewiththenewversion,inthesamewayastheinitialinstall.
Firstcopythedownloadtarballto/tmpandunpackwith:
$tarxkjvfamberdmsbsVERSION.tar.bz2
Removetheexistingversion:
$rmrf/usr/share/amberdms/billing_system
Copythenewversionfromtheunpackedtarball
$cpvramberdmsbsVERSION/usr/share/amberdms/billing_system
Createsymlinkforconfigurationfile
$lns/etc/amberdms/billing_system/config.php/usr/share/amberdms/billing_system/include/configsettings.php
Installnewcronfile
$cp/usr/share/amberdms/billing_system/help/resources/amberdmsbscron/etc/cron.d/amberdmsbs
Setpermissionsthisisimportant,sinceweneedtolimitwhatuserscanreadfilessuchasconfiguration.Theapacheusercanbe
nameddifferentlyonsomesystems,typicallyApacheisrunaseither:

wwwdata(DebianandUbuntu)

apache

apache2

httpd
Ifyouareunsure,checktheUsersettingsintheApacheconfigurationfiles.Fortheseinstructionsweassumeapacheforthe
webserverandcronforthecrondaemon.
$chownRroot:apache/etc/amberdms/billing_system
$chmodR750/etc/amberdms/billing_system
$chmodR644/etc/cron.d/amberdmsbs
Copyright2010AmberdmsLtd

Page12/13

ABSManualInstallationGuide

$chmodR755/usr/share/amberdms/billing_system
Thiscompletestheupgradeoftheapplicationfiles,nowmoveontothedatabaseinstallationinthefollowingsection.

5.3. Upgradingthedatabase
Toupgradethedatabase,aneasytousescripthasbeenprovided,whichreadsthesettingsinyourconfigurationfile,checksthe
currentschemaversionofthedatabaseandthenappliesallthedatabaseconfigurationchangesthatarerequired.
$cd/usr/share/amberdms/billing_system/
$help/resources/schema_update.plshelp/schema/c/etc/amberdms/billing_system/config.phpv
Thekeyoptionsare:
s
Locationofthehelp/schema/directory.
c
Locationoftheconfigurationfile.
v
Verbosedetailstheactionstaken.
OncetheSQLupgradehasbeencompleted,youwillbeabletologintothebillingsystem.Iftheupgradeisunsuccessful,userswill
beunabletologintopreventunexpectedbehaviourofthebillingsystem.

Copyright2010AmberdmsLtd

Page13/13