Installing from Release - Documentation topics on: getting started,installation,installing dotcms,.

Installing from Release

This document details the steps needed to install dotCMS from the .zip or tar.gz distribution, including installation steps, descriptions and example commands to execute on the server. All the example commands need to be modified based on the database and operating system that you are using.

Install Java

1. Download and install Java JDK 1.8 (either Oracle or OpenJDK).

2. Ensure that you are running Java 1.8

Run the following command at the command prompt and make sure that the version displayed is Java 1.8:

java -version

3. Verify that your JAVA_HOME environment variable is set correctly.

Make sure that you have a JAVA_HOME environment variable that points to the root of the jdk install directory.

  • IMPORTANT: The path specified in your JAVA_HOME variable should not contain spaces.
    • This means that on Windows the path in your JAVA_HOME environmental variable must use 8.3 names and must not contain spaces, for example:
      JAVA_HOME=C:\Progra~1\Java\jre-1.8.0_65\
      

Download and Install dotCMS

4. Download dotCMS

Download the latest dotCMS zip file (for Windows), or tar.gz (for Linux/OS-X/Unix), from the dotCMS Downloads page.

The dotCMS distributions are named dotcms_X.X.x.zip or dotcms_X.X.tar.gz respectively.

5.Unzip the dotCMS distribution into its own folder.

Important: The folder name and path to the folder must NOT contain spaces.

  • Linux/OS-X/Unix:
    • To extract the files in the current directory, decompress the dotCMS tar.gx file using the following syntax:
      tar -zxvf dotcms_X.X.tar.gz
      
    • To extract the files to a specific directory, use the following syntax instead:
      tar -zxvf dotcms_X.X.tar.gz -C /tmp/extract_here/
      
  • Windows:
    unzip dotCMS_x.x..zip
    

Configure the dotCMS Database

By default, dotCMS is configured to start up in an H2 database for evaluation and development. To run dotCMS in H2DB, no database configuration is required.

Important: H2DB should NOT be used for a production in environment.

  • To startup a public development or production server, configure any one of the standard databases (Postgres, MySQL, Oracle, or MS SQL Server). To install dotCMS in a .war, please see the WAR Installation documentation.

6. Create the Database

  • Be sure to review database specific requirements documentation BEFORE setting up your database.
  • Create a new database called dotCMS with UTF-8 encoding and default collation.
  • Create a user that has access to the dotCMS database and grant that user “create all” privileges (including triggers, procedures, types and functions) for the dotCMS database.
  • Important: Do not manually run SQL commands or .sql files.
    • On initial start up, dotCMS will to create the database schema and initial data it needs.

7. Edit the database connection properties

Edit the database connection properties in the context.xml file ($DOTCMS_HOME/dotserver/tomcat-X.xx/webapps/ROOT/META-INF/context.xml).

Note: It is strongly recommended that you use a ROOT folder plugin to store all configuration changes, to ease deployments and future upgrades.

  • Comment out the H2DB configuration.
  • Uncomment the configuration for the database you are using.
  • Update the last part of the URL to your database name.
  • Change the username:password to the appropriate values for your new dotCMS database.

The following is an example of a postgresql config pointing to a database named dotCMS.

<!-- POSTGRESQL -->
<Resource name="jdbc/dotCMSPool" auth="Container"
      type="javax.sql.DataSource"
      driverClassName="org.postgresql.Driver"
      url="jdbc:postgresql://127.0.0.1/dotcms"
      username="postgres" password="xxxxx" maxTotal="60" maxIdle="10" maxWaitMillis="60000"
      removeAbandonedOnBorrow="true" removeAbandonedOnMaintenance="true" removeAbandonedTimeout="60" logAbandoned="true"
      timeBetweenEvictionRunsMillis="30000" validationQuery="SELECT 1" testOnBorrow="true" testWhileIdle="true" />

Configure dotCMS

8. Set the Server IP Address and Port

By default, dotCMS will run on localhost on port 8080. If you need dotCMS to run on a particular IP address, you can specify it in the Tomcat server.xml file (/dotserver/tomcat-X.xx/conf/server.xml).

Note:

  • It is strongly recommended that all changes to he server.xml file be made through a ROOT folder plugin.
  • If you wish to run dotCMS on port 80 you must have root or sudo access.
  • If you are running dotCMS on an application server other than Tomcat, you will need to change the server configuration in whatever way is appropriate for your application server.

Find the <Server> and <Connector> tags. Set the address property in the <Server> tag and the port property in the <Connector> tag. For example:

<Server address="208.250.1.102" port="8005" shutdown="SHUTDOWN" debug="0">
...
<Connector connectionTimeout="20000" port="8080" protocol="HTTP/1.1" redirectPort="443"/>

Note: The port in the <Server> tag is the port of the dotCMS server, and the port in the <Connector> tag is the port used to access your dotCMS web site. It is recommended that you do not change the port in the <Server> tag unless you are using a cluster configuration, or you have a port conflict with another application running on the same application server.

9. Linux, OS-X, and UNIX (only): Change the /bin Scripts Permissions

Add execution permission to all shell scripts (*.sh) in the bin directory:

cd $DOTCMS_HOME
chmod 755 ./bin/*.sh
chmod 755 dotserver/tomcat-X.xx/bin/*.sh

Start and Access dotCMS

10. Start the dotCMS Server

  • Start the dotCMS server using the supplied shell script
    • Linux/OS-X/Unix: bin/startup.sh
    • Windows: bin/startup.bat
  • Check the log output. For example:
    tail -n 1000 -f ./dotserver/tomcat-X.xx/webapps/ROOT/dotsecure/logs/dotcms.log
    

Note:

  • When dotCMS initially starts up, it automatically creates all the database tables and import the site data found in the file $DOTCMS_HOME/dotserver/tomcat-X.xx/webapps/ROOT/starter.zip.
  • On Windows we suggest that you download the excellent baretail tool and use it to monitor the logs.
  • It is not uncommon to see some warnings in the logs, depending on your configuration.
    • However if you see any errors in the logs, it is likely something has gone wrong.
      • Check your address, connection and database settings to make sure everything is correct, and try again if necessary.

If, after you have started dotCMS, the database tables and data are not found, then something went wrong. If this happens:

  1. Make sure your dotCMS database user has create privileges on the dotCMS database.
  2. Check your database connection properties to ensure you have configured dotCMS with the correct database server information.
  3. Drop the dotCMS database.
  4. Create a new dotCMS database and try again.

11. Browse the starter site

You can access the starter site by browsing the IP address and port specified in your configuration. For example, if you've installed dotCMS on your local server on the default port (8080), you can browse the starter site by visiting http://localhost:8080.

12. Login to the dotCMS Backend

You can login to the dotCMS administration console (backend) by appending /admin to the web site address. For example, https://localhost:8080/admin.

Use the following credentials to login to the admin console on the dotCMS starter site:

  • User: admin@dotcms.com
  • Password: admin

Getting Help

  • Need help installing dotCMS?
    • Please search the dotCMS forum and please feel free to post any questions or comments.
  • Need more help?