Professional Documents
Culture Documents
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
sales@amberdms.com
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
support@amberdms.comwithanyquestions.
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