[opencms-dev] Installation Dokumentation

[Steffen Petter]

Hello list members,

here some additional comments for the installation of opencms (4.1.36 and
4.0.30)
My comments are enclosed by begin tag <comment_from _steffen> and the end
tag </comment_from_steffen>

----------------------------------------------------------------------------
----------

<installation_guide>

Step 1
Install the Apache Web Server.

<comment_from_steffen>
You can also use TOMCAT as a Java Servlets and JavaServer Pages Reference
Implementation from the Apache Group.  See http://jakarta.apache.org .
</comment_from_steffen>


Check that your server is working by requesting an example page (e. g. the
demo index.html coming with the apache distribution).

Step 2
Install the Java JDK (from SUN or IBM) and the Apache JServ 1.0. OpenCms
currently works only with version 1.0. For details on how to install these
components on your operating system, see the documentation that comes with
them.

<comment_from _steffen>
Make sure that you update the PATH variable with JDK bin directory, e.g.
...:/usr/java/bin on UNIX and ...;C:\jdk\bin on WIN32.
</comment_from_steffen>

Check that a Jserv Servlet Zone is set up properly and running on your
machine by requesting the default IsItWorking class coming with JServ.

<comment_from_steffen>
You can check the status with http://localhost/jserv
</comment_from_steffen>

Step 3
Install mySQL (see the mySQL documentation on how to do this). Please
remember that mySQL is shareware and you have to pay for it if you use it
for a commercial purpose.
Make sure mySQL is running before you continue by starting the mySQL monitor
(command mysql in your mySQL bin folder). The database works correctly, if a
mySQL prompt appears after calling the monitor. You can exit and go on to
the next step.

<comment_from_steffen>
Make sure that the max_allowed_packet variable is set up with the minium
value of 2M. It is necassary for the later OpenCMS setup routine, because
some data blocks are bigger than the standard value of 1M. You can do this
by start the mysql daemon like: bin/safe_mysql -O max_allowed_packet=2M &
</comment_from_steffen>

Step 4
Unzip the OpenCms distribution (opencms_40xxx.zip <comment_from_steffen>for
the latest stable version or opencms_4.1.xx.zip for the latest development
version</comment_from_steffen>).  We currently have no RPM or setup.exe
available, but this is a planned project for the future.
Copy the opencms.properties from the config folder and the opencms.jar to
your servlets directory.
Copy the pics folder residing in the workplace to your apache document root
folder.
Create two new folders ExternalComponents and logs in your servlet
directory.
Get the database driver mysql_uncomp.jar and xerces.jar described in
Components and copy them to the newly created ExternalComponents folder and
to the opencms folder extracted from the zip file.
Your servlets folder now looks like this:
(your servlet path)/servlets/ExternalComponents/xerces.jar
(your servlet path)/servlets/ExternalComponents/mysql_uncomp.jar

<comment_from_steffen>
[(your servlet path)/servlets/ExternalComponents/activation.jar] ##needs for
mail support
[(your servlet path)/servlets/ExternalComponents/mail.jar] ##mail support
</comment_from_steffen>

(your servlet path)/servlets/logs/
(your servlet path)/servlets/opencms.jar
(your servlet path)/servlets/opencms.properties


Step 5
For setting up the opencms database cd to config in the extracted opencms
folder. Create a new database by
mysqladmin create opencms41
Finally run
mysql opencms41 < mysql.sql

<comment_from_steffen>
mysqladmin --user=root -p create opencms ##for version 4.0.30.
or mysqladmin --user=root -p create opencms41 ##for version 4.1.xx
Finally create the database structure with an SQL-dump:
mysql opencms < mysql.sql  ##for version 4.0.30
mysql opencms < mysql.sql  ##for version 4.1.xx

Check this by calling the MySQL monitor:
mysql --user=root -p opencmsXX

and type the following command at the mysql prompt
mysql> SHOW TABLES;

Following tables should be print out:
version 4.0.30
+--------------------------+
| Tables in opencms        |
+--------------------------+
| CMS_FILES                |
| CMS_GROUPS               |
| CMS_GROUPUSERS           |
| CMS_METADEF              |
| CMS_METAINFO             |
| CMS_PROJECTS             |
| CMS_PROPERTIES           |
| CMS_RESOURCES            |
| CMS_USERS                |
| CMS_USERS_ADDITIONALINFO |
| GlobeTask                |
| GlobeTaskLog             |
| GlobeTaskPar             |
| GlobeTaskType            |
+--------------------------+

version 4.1.xx (4.1.36)
+----------------------+
| Tables in opencms41  |
+----------------------+
| CMS_FILES            |
| CMS_GROUPS           |
| CMS_GROUPUSERS       |
| CMS_PROJECTS         |
| CMS_PROPERTIES       |
| CMS_PROPERTYDEF      |
| CMS_RESOURCES        |
| CMS_SESSIONS         |
| CMS_SYSTEMID         |
| CMS_SYSTEMPROPERTIES |
| CMS_Task             |
| CMS_TaskLog          |
| CMS_TaskPar          |
| CMS_TaskType         |
| CMS_USERS            |
+----------------------+

</comment_from_steffen>

This will create all required database tables.
Make sure all tables are created properly by calling the mySQL monitor again
with mysql opencms41 and entering show tables at the monitor prompt. mySQL
prints out the following list of tables:
+--------------------------+
  Tables in opencms41
+--------------------------+
  CMS_FILES
  CMS_GROUPS
  CMS_GROUPUSERS
  CMS_PROJECTS
  CMS_PROPERTIES
  CMS_RESOURCES
  CMS_SYSTEMID
  CMS_SYSTEMPROPERTIES
  CMS_USERS
+--------------------------+

Step 6
Edit the opencms.properties and set the path for the log file:
log.file=(your servlet path)/servlets/logs/opencms.log
On UNIX systems the apache may have problems writing to the logs folder. For
this reason you should set its owner to nobody.
Change the export path of config/cmssetup.txt to an existing empty folder in
the line beginning with "writeExportPath" (You will find these lines near to
the end of the file). cd to the parent opencms folder and initialize the
database with all workplace default files by calling the following command:
java -mx64M -classpath opencms.jar:xerces.jar:mysql_uncomp.jar
com.opencms.core.CmsShell
config/opencms.properties < config/cmssetup.txt

<comment_from_steffen>
change in your servlet directory and type the following command:

java -mx64M -classpath
opencms.jar:ExternalComponents/xerces.jar:ExternalComponents/mysql_uncomp.ja
r
com.opencms.core.CmsShell
opencms.properties <
/your/opencms/installation/directory/config/cmssetup.txt
 </comment_from_steffen>

This must be written in one single command line. The Java binary java should
reside in the bin folder of your JDK installation. If there is no Java
binary available on your system but only a Java runtime environment, you may
replace the java command by jre.
On Windows environments you have to replace the colons used as classpath
separators by semicolons.
Some Java VM need additional settings for the classpath. Try to add the
current directory . and (for JDK 1.1.x) the classes.zip in the lib folder of
your JDK installation to your classpath, if the command above doesn't work
and throws a ClassNotFoundException.
The OpenCms database is now set up completely. You are now able to check the
basic OpenCms system. Call the OpenCms console by entering
java -mx64M -classpath opencms.jar:xerces.jar:mysql_uncomp.jar
com.opencms.core.CmsShell
config/opencms.properties

<comment_from_steffen>
change in your servlet directory and type the following command:

java -mx64M -classpath
opencms.jar:ExternalComponents/xerces.jar:ExternalComponents/mysql_uncomp.ja
r
com.opencms.core.CmsShell
opencms.properties
</comment_from_steffen>

(This command is similar to the one above. Note that
CmsInitMySqlFillDefaults changed to CmsInitMySql and the pipe <
config/cmssetup.txt is missing now.)

<comment_from_steffen>
(This command is similar to the one above. Note that <
/your/opencms/installation/directory/config/cmssetup.txt is missing now.)
</comment_from_steffen>

Log in as Admin and check the accessibility of a workplace file in your
database:
> login Admin admin
> readFile "/system/workplace/action/start.html"
The OpenCms console answers with
[Resource]:/system/workplace/action/start.html , Project=1 , User=1 ,
Group=1 : Access=rwvrwvr-v- : Resource-type=2

Step 7
Finalize the configuration of your servlet zone. Make sure that your
jserv.conf contains the line
ApJServMount /servlets /root
and the jserv.properties contains
zones=root
wrapper.bin.parameters=-mx64M
and
root.properties=(your servlet configuration path)/zone.properties
Update your zone.properties and set the following repositories:
repositories=(your servlet path)/servlets/opencms.jar
repositories=(your servlet path)/servlets/ExternalComponents/xerces.jar
repositories=(your servlet
path)/servlets/ExternalComponents/mysql_uncomp.jar

<comment_from_steffen>
repositories=(your servlet path)/servlets/ExternalComponents/activation.jar
repositories=(your servlet path)/servlets/ExternalComponents/mail.jar
</comment_from_steffen>


and add the lines:
servlet.opencms.code=com.opencms.core.OpenCmsServlet
to the Servlet Aliases section and
servlet.opencms.initArgs=properties=(your servlet
path)/servlets/opencms.properties
to the Servlet Init Parameters section. Edit the opencms.properties and set
the path for the log file:
log.file=(your servlet path)/servlets/logs/opencms.log
On UNIX systems the apache may have problems writing to the logs folder. For
this reason you should set its owner to nobody.

Step 8: Now your system is ready!
Start your web server. The OpenCms system is available at
http://your.server/servlets/opencms/system/workplace/action/login.html.
Login as Admin with the default password admin.

Step 9: Security
After you have managed to install OpenCms you should have a look at the
security. Change the admin password of OpenCms by calling the user
preferences ("hammer" icon on the workplace main screen). After that you can
add a password to the mySQL database. Enter the following commands at the
mySQL command line.
> use mysql;
> insert into user values ('localhost', 'ocmsuser',
password('XXXXX'),'N','N','N','N','N','N','N','N','N','N','N','N','N','N');
> insert into db values ('localhost', 'opencms41', 'ocmsuser',
'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y');
> flush privileges;

Don't forget to add the new user and his password into all connect strings
to the database. The new user can now only connect to the OpenCms tables.
For more informations see the mySQL documentation.

Troubleshooting
Look at all available log files (here with the paths used in a standard UNIX
installation), if you have problems with calling the login screen:
Apache log file (/usr/local/apache/logs/error_log)
JServ module log file (/usr/local/apache/logs/mod_jserv.log)
OpenCms log file ((your servlet path)/servlets/logs/opencms.log)

Setting up with different components
OpenCms is developed and tested in the environment described in Components.
If you managed to setup OpenCms with different components, please let us
know. You might send your configuration information to
documentation at opencms.com.

Documentation
Obviously, this documentation could be much improved. If you want to help us
writing a better installation documentation, send an email to
documentation at opencms.com.

Professional Support
For professional support in installing OpenCms, please see the support page.

</installation_guide>