Opencms Handbook 1.0 Public.doc

lerhema computersysteme ag21/03/2020opencms handbookhttp:/www.hema.chversion 1.0.publicopencms handbookthis handbook describes how to install a complete opencms system with multiple sites to a windows 2000 server environment. server configuration overview3webserver installation (iis)4development site setup4staging site setup4live site setup5java sdk installation (sun)5tomcat installation (jakarta)5file encoding5xerces issues6database installation (mysql)6cms installation7setup opencms war file7opencms setup wizard7file synchronisation (filesyncserver)9filesyncserver installation9service user setup10configuration file setup11sample configuration12configuring an opencms site13site setup13add users13remove unwanted modules / pages14setup file system structure14add site as new module15create project for site16setup user settings17configure templates18add xml template18add jsp template19add jsp navigation template20add blank page template22adding resources22add css file22configuring static export22configuring the file system (export properties)23configuring the perties file24using opencms25adding a page25editing a page26wysiwyg editor tips26uploading images26deleting / copying / moving a page28publishing28publishing the site28publishing a single page29publishing and navigation issues with static export29publishing tips29opencms modules (#incomplete)30installing a module30news module30photo album module30resources31links31opencms server installationthere are several packages which are required by opencms. a webserver, tomcat, a database. opencms, filesyncserver, and opencms modules.applicationdescriptionproductlinkwebserveriisjava sdksun java sdk/j2se/java jsp containertomcat/tomcat/databasemysql/cms systemopencmsfile synchronisationfilesyncserverorsecondcopyserver configuration overviewwebserver installation (iis)i currently allow for three stages during www productiondevelopment staging livethere is no need for the development and staging servers to have a public ip. we have added a port mapping to the firewall so that opencms may be accessed from outside.opencms uses port 8080 (although this can be changed at setup, i recommend using the default).development site setupno action required (see cms installation)staging site setupthe development server and staging server can live on the same machine. setup iis with a host header (site) for each opencms development instancenote : windows 2003 iis 6.0 has an upload limit of about 200 kbsolution iis 6.0 (windows 2003) has a file named metabase.xml which resides in the c:windowssystem32inetsrv folder. navigate to that directory and edit the file. search for an entry called aspmaxrequestentityallowed. this defaults to a value of 204800, which causes iis 6.0 to limit allowed upload size to 204,800 bytes. changing this value to a large number (such as 2000000000 for 2 gigabytes) will allow your windows 2003 server to accept large uploads. if your server does not allow the metabase edit-while-running feature, you will need to stop the iis service before you can save the metabase.xml file.information found at : /show.asp?code=ps030911112 onlineand add a reference to the site within my hosts file (although this could be done through setting up a proper dns)c:windowssystem32driversetchosts# -# staging:1: opencms server#1 opencms.test01.chlive site setupthis is the actual live www server and will not be discussed here. java sdk installation (sun)download the j2se (standard edition) sdk from /j2se/. install to the server by executing downloaded file.do not use the jre (java runtime environment) opencms must have the sdk (software development kit).tomcat installation (jakarta)get a release build tomcat from /site/binindex.cgi.install tomcat as a service (this is probably the default installation on windows).i have installed tomcat on the staging server to e:tomcat4.1file encodingby default tomcat uses a different encoding system as opencms. this needs to be changed to iso-8859-1.use regedit to edit the following key : hkey_local_machinesystemcurrentcontrolsetservicesapache tomcat 4.1parametersadd change the following keysactionkeyvalueaddjvm option number xwhere x is probably 3-dfile.encoding=iso-8859-1updatejvm option countincrement by 14xerces issuesthere are issues with opencms 5.0.2 and later versions of tomcat. these issues relate to an incompatible xerces jar. more information can be found be searching for xerces on /opencms/en/development/mailinglist-archive.html. however, when using a newer build of opencms, this should not be an issue.database installation (mysql)download mysql from /downloads/index.html. it is also worth getting the control center from /downloads/mysqlcc.html.install the products.edit myini c:winntmy.inimake sure the e:mysqldatabase folder exists. databases will be written here.the max_allowed_packet=100m is to allow larger files to be uploaded to opencms.#this file was made using the winmysqladmin 1.4 tool#17.07.2003 13:35:49#uncomment or add only the keys that you know how works.#read the mysql manual for instructionsmysqldbasedir=c:/programme/mysql#bind-address=07datadir=e:mysqldatabase#language=c:/mysql/share/your language directory#slow query log#=#tmpdir#=#port=3306#set-variable=key_buffer=16mset-variable=max_allowed_packet=100mwinmysqladminserver=c:/programme/mysql/bin/mysqld-nt.exeuser=rootpassword=*note : password=* needs to be changed to whatever.cms installationthe opencms system is downloaded as a zip file. within the zip file is a .war file. the war file should renamed to the name of the required new opencms instance and then copied to the tomcat webapps directory (e:tomcat4.1webapps). this process will need to be carried out for every individual instance required for opencms (ie. for each customer)setup opencms war file1. extract opencms.war file from opencms install zip.2. rename opencms.war to cms_test01.war (where test01 is a reference name for the new site)3. copy cms_test01.war to e:tomcat4.1webapps4. open browser and goto url http:/staging.www.server:8080/cms_test01/ocsetup/opencms setup wizard12follow the wizard using standard setup.add password for root account (same password as set in mysql my.ini)ideally, one should use a different user here rather than root.34creating database and creating tables should both be marked as ok.both the jdk and tomcat should be detected. you should see the following message your system uses components which have been tested to work properly with opencms.56import the workplace, but switch directory translation offthe workplace will be imported this may take a few minutes78click the here linkclick the /cms_test01/opencms/system/login/ linkwhere test01 is the name of the instance.9logon with username : admin password : adminfile synchronisation (filesyncserver)this is required to allow files to be synchronised from the staging site to the live site.files need to be copied from the staging site eg. staging.www.server wwwroottest01 to live.www.serverwwwroottest01.there are a few possibilities here : filesyncserver (preferred) secondcopy batch file called by scheduled taskhowever we will only look at the filesyncserver.file sysncronisation is required due to the fact that opencms cannot export files to any machine other than the one it is running on. ie. it is not allowed to access shared drives. this is a limitation/security policy from java.filesyncserver installationget filesyncserver from http:/www.oblivion.ch/downloads/.unzip and run the setup on the staging server.at the current time this service has not been made public, but it will become public in the next few months. i need to do a lot more testing on it and create a proper help file for it.this service will only run on pcs with the .net framework 1.0 or greater installed.service user setupsetup a user with access to both the source (staging) and target (destination).i have set up a user called filesync on both staging and live.www.server with the same password and given writes to the user on the required directories.staging.www.serverlive.www.serverset the filesyncservice to run under the new user, filesync which is setup on both machines with the same password. or if both machines are in the same domain, make sure the service runs under a domain user account which has permissions to both target and destination folders.configuration file setupthe configuration file (and log file) can be accessed through the programme menu. it is located at %programfiles%viralburnfilesyncsconfig.xmlthere is also a corresponding dtd file which describes a valid xml configuration file.edit the configuration file for any new opencms instance which is required to be synchronised.note: there should not be a need to restart the service after changes to the configuration file, however, i would recommend that the service is restarted.the log is located at c:programmeviralburnfilesyncslog.txtsample configurationthe item tag represents an opencms item (or a copy profiile). we can also add filter tags to the item to exclude specific folders. always exclude the siteaspnet_client folder. iis seems to create this automatically and we dont want to copy it.sample configuration file : configuring an opencms sitefor each required site, a new war file should have been created and installed and setup (see cms installation).assuming that a new site test01 is to be configured and the cms system has been setup we shall now configure the site.site setuplogin to the cms system using the url http:/staging.www.server:8080/cms_test01/opencms/system/login/and login with admin, adminadd usersgo to the administration view in opencms.go into the user management module.click on the edit users buttonclick on the new button and set up the user as shown belowmake sure the user belongs to both the administrators and projectmanager groups (this seems to alleviate a lot of rights problems. i have not totally figured out how the rights system works.)set the start with group option to users. this will mean that any pages created by the user will be set with users rights.logoff and logon again using the new user to logon.remove unwanted modules / pagesgo to the administration view and go into the module management modulethere will probably be two modules : org.opencms.default and org.opencms.welcomechange to the offline projectleft click on each modules icon and select deletechanging back to explorer view will now show that several pages have also been removed (eg. the index.jsp file in the root folder).setup file system structurein the explorer view click the root folder, make sure you are in the offline project and create two new folders called www and resourcesdo not add the folder to navigation.the file system should now look like the following :add site as new modulechange to administration view and go to the module management module.change to offline project if not already selected.create a new modulethe package name should be the site url written backwards. eg. www.hema.ch would be ch.hema.www.set the version to 1.0.fill out all other options, this is not an administrations point.after clicking ok, you will be returned to the module management overview.select the new module (left click) and select administratecontinue to the next window of the module administration wizard (depends on properies).continue to the next window of the module administration wizard. (module properties)click the new button to add a new propertyadd a new string property with the followingname :additionalresourcestype :stringvalue :/www/;/system/galleries/description :additional resources that belong to this module. please note: if you delete this module, all resources listed here will be deleted (even if they are directories).this will ensure that all required files will be exported with the module during a module export.click finish on the wizard.publish the site by clicking the publish buttonthis will update the system with the new modulecreate project for siteclick back to go to the main administration view pagego to the project management moduleclick on the new project icongive the project a name.select the add folder icon and expand the folder selection view so you can see the ch.test.www under modules.click on the ch.test.www folder, the www, and the resources folder. these will be added to the folders: box.set the user group as users and manager group as projectmanager.click ok to save the project.setup user settingsclick on the preferences icon (in the top navigation window)and click on the startup options tab in the preferences windowset the users preferred language and set the start with project: to the new project just previously created (ie. testadmin).configure templatesadd xml templatexml templates are stored in the /system/modules/ch.test.www/templates/ folder.navigate to this folder and add a new blank text pagegive the page a name (eg. test).i usually give the title something like 01 main template. the 01 helps in sorting the templates in selection lists and as this is our main template, we want it to be first in any selection list.edit the template source code by left clicking its icon and then selecting edit source. in order to edit any file, it must first be locked. this can be seen by the padlock next to a file. if it is not locked, write click the file icon and select lock.after editing, a file should be unlocked to make it available to others.add the following code to the file and save and close it using the icon /resources/css/test.css com.opencms.flex.cmsjsptemplate ./jsptemplates/test.jsp the marked text in the file shows which parts may need changing to reflect the current site / project.this xml template has a reference to a jsp template called test.jsp which we will define in the next step.add jsp templatenavigate to the /system/modules/ch.test.www/jsptemplates/ folder.note : if it does not exist, create it !create a new jsp file called test.jsp.add the