Using a Different System?
-
How to Install dotCMS on Ubuntu 16.04
dotCMS is an open source enterprise grade content management system written in Java. It contains nearly every feature required to create a website for your business. It provides a RESTful API to integrate with other services such as CRM, mobile applications, and more. It uses Elasticsearch for real-time indexing of content and Redis for implementing multi-tier cache.
This article was written for dotCMS 4.2.2, however the instructions provided may work for newer versions as well.
Prerequisites
- A Vultr CentOS 7 server instance.
- A sudo user.
- A domain name pointed towards the server.
For this tutorial, we will use 192.168.0.1
as the public IP address and cms.example.com
as the domain name pointed towards the Vultr instance. Please make sure to replace all occurrences of the example domain name and public IP address with the actual one.
Update your base system using the guide How to Update CentOS 7. Once your system has been updated, proceed to install Java.
Install Java
OpenJDK can be easily installed as the package is available in the default YUM repository.
sudo yum -y install java-1.8.0-openjdk-devel
If Java is installed correctly, then you will be able to verify its version.
java -version
You will get a similar output.
[user@vultr ~]$ java -version
openjdk version "1.8.0_151"
OpenJDK Runtime Environment (build 1.8.0_151-b12)
OpenJDK 64-Bit Server VM (build 25.151-b12, mixed mode)
Before we can proceed further, we will need to set up the JAVA_HOME
and JRE_HOME
environment variables. Find the absolute path of the Java executable on your system.
readlink -f $(which java)
You will see a similar output.
[user@vultr ~]$ readlink -f $(which java)
/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.151-1.b12.el7_4.x86_64/jre/bin/java
Now, set the JAVA_HOME
and JRE_HOME
environment variables according to the path of the Java directory.
echo "export JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.151-1.b12.el7_4.x86_64" >> ~/.bash_profile
echo "export JRE_HOME=/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.151-1.b12.el7_4.x86_64/jre" >> ~/.bash_profile
Execute the bash_profile
file.
source ~/.bash_profile
Now you can run the echo $JAVA_HOME
command to ensure that the environment variable is set.
[user@vultr ~]$ echo $JAVA_HOME
/usr/lib/jvm/java-1.8.0-openjdk-1.8.0.151-1.b12.el7_4.x86_64
Install PostgreSQL
By default, dotCMS is configured to use the H2 database engine. The H2 database engine is a flat file based database engine. It is not recommended to use in production. In this tutorial, we will use PostgreSQL server to store the dotCMS database.
PostgreSQL is an object-relational database system and known for its stability and speed. Add the repository of the latest release of PostgreSQL into the system.
sudo yum -y install https://download.postgresql.org/pub/repos/yum/10/redhat/rhel-7-x86_64/pgdg-centos10-10-1.noarch.rpm
Install the PostgreSQL database server.
sudo yum -y install postgresql10-server postgresql10-contrib postgresql10
Initialize the database.
sudo /usr/pgsql-10/bin/postgresql-10-setup initdb
Start the PostgreSQL server and enable it to start automatically at boot time.
sudo systemctl start postgresql-10
sudo systemctl enable postgresql-10
Change the password for the default PostgreSQL user.
sudo passwd postgres
Log in as the default PostgreSQL user.
sudo su - postgres
Create a new PostgreSQL user for dotCMS.
createuser dotcms
PostgreSQL provides the psql
shell to run queries on the database server. Switch to the PostgreSQL shell.
psql
Set a password for the newly created user for the dotCMS database.
ALTER USER dotcms WITH ENCRYPTED password 'DBPassword';
Replace the database user password DBPassword
with a secure password. Create a new database for the dotCMS installation.
CREATE DATABASE dotcms OWNER dotcms;
Exit from the psql
shell.
/q
Switch to the sudo
user.
exit
Install dotCMS
Download the dotCMS archive.
wget https://dotcms.com/physical_downloads/release_builds/dotcms_4.2.2.tar.gz
You can always find the link to the latest version of the application on the dotCMS download page.
Create a new directory to store the dotCMS files and extract them into it.
sudo mkdir /opt/dotcms
sudo tar -zxf dotcms*.tar.gz -C /opt/dotcms
Open the database configuration file.
cd /opt/dotcms
sudo nano dotserver/tomcat-*/webapps/ROOT/META-INF/context.xml
Find the H2
block.
<!-- H2 -->
<Resource name="jdbc/dotCMSPool" auth="Container"
...
validationQuery="SELECT 1" testOnBorrow="true" testWhileIdle="true" />
Comment out the whole H2
section by replacing the comment delimiter -->
from the start of the section to the end of the section. It should look like the following.
<!-- H2
<Resource name="jdbc/dotCMSPool" auth="Container"
...
validationQuery="SELECT 1" testOnBorrow="true" testWhileIdle="true" />
-->
Uncomment the PostgreSQL section by removing the comment delimiter -->
from the end of section and placing it on the top wrapping POSTGRESQL
. Also, find username=
and password=
and replace the existing values with the username and password of your PostgreSQL database user. If you have used a database name other than dotcms
, then you will need to change the database name in url=
. Once configured, the PostgreSQL block in the file should look like the following.
<!-- POSTGRESQL -->
<Resource name="jdbc/dotCMSPool" auth="Container"
type="javax.sql.DataSource"
factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
driverClassName="org.postgresql.Driver"
url="jdbc:postgresql://localhost/dotcms"
username="dotcms" password="DBPassword" maxTotal="60" maxIdle="10" maxWaitMillis="60000"
removeAbandonedOnBorrow="true" removeAbandonedOnMaintenance="true" removeAbandonedTimeout="60" logAbandoned="true"
timeBetweenEvictionRunsMillis="30000" validationQuery="SELECT 1" testOnBorrow="true" testWhileIdle="true" />
Provide the execution permission for all the executable files.
sudo chmod 755 ./bin/*.sh
sudo chmod 755 dotserver/tomcat-*/bin/*.sh
dotCMS is now installed on your server. To immediately run the application, execute the following.
cd /opt/dotcms
sudo bin/startup.sh
You will see the following output when the server has started successfully.
[user@vultr dotcms]$ sudo bin/startup.sh
Using DOTCMS_HOME = /opt/dotcms/dotserver/tomcat-8.0.18/webapps/ROOT
Using DOTSERVER = dotcms
Using CATALINA_PID = /tmp/dotcms.pid
Using JAVA_OPTS = -Djava.awt.headless=true -Xverify:none -Dfile.encoding=UTF8 -server -XX:+DisableExplicitGC -XX:MaxMetaspaceSize=512m -Xmx1G -XX:+UseG1GC -javaagent:/opt/dotcms/dotserver/tomcat-8.0.18/webapps/ROOT/WEB-INF/lib/byte-buddy-agent-1.6.12.jar -Ddotserver=dotcms
Using CATALINA_BASE: /opt/dotcms/dotserver/tomcat-8.0.18
Using CATALINA_HOME: /opt/dotcms/dotserver/tomcat-8.0.18
Using CATALINA_TMPDIR: /opt/dotcms/dotserver/tomcat-8.0.18/temp
Using JRE_HOME: /
Using CLASSPATH: /opt/dotcms/dotserver/tomcat-8.0.18/bin/bootstrap.jar:/opt/dotcms/dotserver/tomcat-8.0.18/bin/tomcat-juli.jar
Using CATALINA_PID: /tmp/dotcms.pid
Tomcat started.
The above command will start the Tomcat web server to serve the application on port 8080
. To check if the dotCMS website is working, allow the required port 8080
through the system firewall.
sudo firewall-cmd --zone=public --add-port=8080/tcp --permanent
sudo firewall-cmd --reload
Open your favorite browser and browse to http://192.168.0.1:8080
. You should see that the application is running a demo website. If you do not see your website, please wait as the first startup of the dotCMS server takes a couple of minutes as it writes data into the PostgreSQL database and builds the cache. You can also check the startup logs.
tail -n 1000 -f /opt/dotcms/dotserver/tomcat-*/webapps/ROOT/dotsecure/logs/dotcms.log
Configure Systemd service
The dotCMS server can be started directly using the startup script provided in the installer package. As a matter of convenience, you should set up a Systemd unit file for the dotCMS server. This will ensure that the application server is automatically started on system restart and failures.
Stop the running dotCMS server using the shutdown script.
sudo bin/shutdown.sh
Create an unprivileged user for running the dotCMS server, for security reasons.
sudo adduser -d /opt/dotcms -s /sbin/nologin dotcms
Provide ownership of the files to the dotCMS user.
sudo chown -R dotcms:dotcms /opt/dotcms
Create a new Systemd service.
sudo nano /etc/systemd/system/dotcms.service
Populate the file.
[Unit]
Description=dotCMS service
After=syslog.target network.target
[Service]
Type=forking
ExecStart=/opt/dotcms/bin/startup.sh
ExecStop=/opt/dotcms/bin/shutdown.sh
User=dotcms
Group=dotcms
Restart=always
[Install]
WantedBy=multi-user.target
Start the application and enable it to automatically start at boot time.
sudo systemctl start dotcms
sudo systemctl enable dotcms
Ensure that the service is running.
sudo systemctl status dotcms
Configure the Reverse Proxy
By default, the dotCMS server listens on port 8080
. We will configure Nginx as the reverse proxy so that the application can be accessed via standard HTTP
and HTTPS
ports. We will also configure Nginx to use SSL generated with Let’s Encrypt free SSL.
Install the Nginx web server.
sudo yum -y install nginx
Start the web server and enable it to automatically start at boot time.
sudo systemctl start nginx
sudo systemctl enable nginx
Install Certbot, which is a client application for Let’s Encrypt CA.
sudo yum -y install certbot
Before you can request the certificates, you will need to allow the ports 80
and 443
or standard HTTP
and HTTPS
services through the firewall. Also, remove port 8080
from the list of firewall exceptions as it is no longer required.
sudo firewall-cmd --zone=public --remove-port=8080/tcp --permanent
sudo firewall-cmd --zone=public --add-service=http --permanent
sudo firewall-cmd --zone=public --add-service=https --permanent
sudo firewall-cmd --reload
Note: To obtain certificates from Let’s Encrypt CA, the domain for which the certificates are to be generated must be pointed towards the server. If not, make the necessary changes to the DNS records of the domain and wait for the DNS to propagate before making the certificate request again. Certbot checks the domain authority before providing the certificates.
Generate the SSL certificates.
sudo certbot certonly --webroot -w /usr/share/nginx/html -d cms.example.com
The generated certificates are likely to be stored in /etc/letsencrypt/live/cms.example.com/
. Let’s Encrypt certificates expire in 90 days, hence it is recommended to set up auto-renewal of the certificates using Cron jobs.
Open the cron job file.
sudo crontab -e
Add the following line at the end of the file.
30 5 * * * /usr/bin/certbot renew --quiet
The above cron job will run every day at 5:30 AM. If the certificate is due for expiration, it will automatically be renewed.
Create a new server block file for the dotCMS site.
sudo nano /etc/nginx/conf.d/cms.example.com.conf
Populate the file.
server {
listen 80;
server_name cms.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443;
server_name cms.example.com;
ssl_certificate /etc/letsencrypt/live/cms.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/cms.example.com/privkey.pem;
ssl on;
ssl_session_cache builtin:1000 shared:SSL:10m;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers HIGH:!aNULL:!eNULL:!EXPORT:!CAMELLIA:!DES:!MD5:!PSK:!RC4;
ssl_prefer_server_ciphers on;
access_log /var/log/nginx/dotcms.access.log;
location / {
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_pass http://localhost:8080;
proxy_read_timeout 90;
proxy_redirect http://localhost:8080 https://cms.example.com;
}
}
Restart the Nginx web server so that the changes can take effect.
sudo systemctl restart nginx
The dotCMS application is now installed on your server for production use. Access the administrative dashboard on the following address.
https://cms.example.com/dotAdmin
Log in using the initial administrator account, admin@dotcms.com
and admin
. Change the default password immediately after login.
Congratulations, the dotCMS content management system is now installed on your server. You can modify the demo site or you can start building your site from scratch.
Want to contribute?
You could earn up to $300 by adding new articles
Suggest an update
Request an article