Installing from Release

Support for “binary” installs of dotCMS is deprecated. New dotCMS deployments should utilize our Docker images.

This document details the steps needed to complete a bare metal install for dotCMS from the .zip or tar.gz distribution, including installation steps, descriptions and example commands to execute on the server. dotCMS requires an external database and and external instance of Elasticsearch to connect to. 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

You may use either of the following JDKs:

• Oracle
• OpenJDK

2. Ensure that you are running Java 11

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

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
  

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 db.properties file $DOTCMS_HOME/dotserver/tomcat_X.X/webapps/ROOT/WEB-INF/classes/db.properties.

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

• 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.

driverClassName=org.postgresql.Driver
jdbcUrl=jdbc:postgresql://localhost/dotcms
username=dotcms
password=dotcms
connectionTestQuery=SELECT 1
maximumPoolSize=100
idleTimeout=10
maxLifetime=60000
leakDetectionThreshold=60000

8. Configure Elasticsearch

Elasticsearch can be configured by editing the dotcms-config-cluster.properties file. Again, this file can be found under the classes directory $DOTCMS_HOME/dotserver/tomcat_X.X/webapps/ROOT/WEB-INF/classes/dotcms-config-cluster.properties. The important properties are these - they need to be pointed to your elasticsearch installation with the appropiate authentication

ES_HOSTNAME=127.0.0.1
ES_PORT=9200
##These settings must be changed on production environments
#ES_AUTH_TYPE can take any of the following values: BASIC or JWT.
#If ES_AUTH_TYPE=BASIC, these properties must be set ES_AUTH_BASIC_USER and ES_AUTH_BASIC_PASSWORD
#If ES_AUTH_TYPE=JWT, a valid token (ES_AUTH_JWT_TOKEN property) must be set
ES_AUTH_TYPE=BASIC
ES_AUTH_BASIC_USER=admin
ES_AUTH_BASIC_PASSWORD=admin

Configure dotCMS

9. Set the Server IP Address and Port

By default, dotCMS will run on localhost on port 8082. 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="8082" 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.

10. 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

11. 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.

12. 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 (8082), you can browse the starter site by visiting http://localhost:8082.

13. Login to the dotCMS Backend

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

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

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

From 22.06 onward, the admin password on the creation of the server will be determined by the INITIAL_ADMIN_PASSWORD configuration option (i.e., the environment variable DOT_INITIAL_ADMIN_PASSWORD). If this option is not set, then it the password will be a random string that can be viewed in the server logs, printed in a wide box made of # characters.

Getting Help

• Need help installing dotCMS?
  • Please search the dotCMS forum and please feel free to post any questions or comments.
• Need more help?
  • Please feel free to contact dotCMS Support about your supported dotCMS products and services.