Entando in production: how to prepare a server, how to deploy your Entando based application

Intro

This guide is aimed at a well defined environment:

• Ubuntu 12.04 LTS - Server - @32bit
• Fresh install, no additions but openssh-server
• Application based on Entando 3.2.0

BTW, we'll be very glad to review any proposed addition for different environments (and bug fixes for this environment, of course)!

Also, be aware that the configurations you'll find here are more or less the default ones with some minor customizations.
Thus, it's up to you to go for the extra mile and harden your server to make it more secure than this!

Conventions

• myportal will be the name of our fictional Entando based application
• www.mydomain.com will be the FQDN (minus the trailing dot) where our fictional Entando based application will be deployed at

Part 1: how to prepare a server

The quick way: only for the brave guy who knows it all

I jotted down a couple of bash scripts which you can use to set up a server in 10 minutes.

If you can't read them and understand every single command, then this is not the way you were meant to follow.

Just skip the rest and go straight to the normal-paced way.

So, for the quick way:

• SERVER: the ip or hostname of the remote machine that you want to prepare for Entando
• LOCAL: your own machine, from which you will launch the scripts pointing to SERVER

1. have a machine with a fresh install of Ubuntu 12.04 LTS Server; this is SERVER
2. install openssh-server on SERVER
3. on SERVER, give root a password so you can now log in as root
4. (optional) on SERVER, have also a regular user which is also a sudoer (more on this later)
5. download somewhere on LOCAL: https://gist.github.com/trumbitta/3973728/raw/e2daa1c135dec6814f1277bc743fcc1baafd9596/provision-entando-1-system-update.sh
6. download somewhere on LOCAL: https://gist.github.com/trumbitta/3973728/raw/9f169d55c4dc71af5e4f81be42b9e2dabdafb659/provision-entando-2-system-environment.sh
7. open and edit provision-entando-2-system-environment.sh, find this block at the very top:

# BEGIN conf
# Edit as needed
HOST_PUBLIC_IP="123.123.123.123"
FQDN="www.mydomain.com"
APPNAME="helloentando"
PG_USER="uentando"
PG_PASSWORD="pentando"
ENTANDO_VERSION="3.2.0"
#
# END conf

and set the appropriate values, knowing that:

• HOST_PUBLIC_IP is the public ip address of SERVER
• FQDN is the FQDN you pointed to SERVER using whatever tool your domain registrar gave you
• APPNAME is the name of the Entando based application you want to deploy on this server
• PG_USER is the username of the user you want to create and use for your application
• PG_PASSWORD is the password you want that user to have
• ENTANDO_VERSION is the version of Entando you want the script to use when it creates a placeholder application for you to check the various configurations when it's done (ok, you should leave this untouched)

1. on LOCAL: cat provision-entando-1-system-update.sh | ssh root@SERVER /bin/bash
2. if you didn't have a regular user on SERVER which is also a sudoer, create it now just like the ending of the previous script suggested you to do (in other words: having it is no more optional at this point)
3. on LOCAL: cat provision-entando-2-system-environment.sh | ssh root@SERVER /bin/bash
4. wait a minute after the final reboot, then point your browser to FQDN and rejoyce

The normal-paced way

(If needed) Getting sudo back

Add a new user

adduser myuser

Make that user a sudoer

adduser myuser sudo

Log off and log back in as that new myuser or as any other sudoer.
From now on, we will assume that the chosen sudoer is myuser.

Install and activate byobu

sudo apt-get --yes install byobu
byobu-enable

Set up proper apt sources and update the system

sudo apt-get --yes install wget
sudo wget https://gist.github.com/raw/3953615/dc45eaf725e63dc5887e12b0c5684e781e1b3fc8/sources.list -O /etc/apt/sources.list
sudo apt-get update
sudo apt-get --yes upgrade

ref: https://gist.github.com/raw/3953615/dc45eaf725e63dc5887e12b0c5684e781e1b3fc8/sources.list

If needed (as is supposed to happen after such an update), reboot.
Byobu will even show an unmistakable icon towards the bottom right corner of the screen.

sudo reboot

Then log back in as myuser

Java

sudo apt-get install --yes openjdk-7-jdk

ref: https://help.ubuntu.com/community/Java#Oracle_.28Sun.29_Java_6

Ant

sudo apt-get install --yes ant ant-contrib

Maven

sudo apt-get install --yes maven2

PostgreSQL

JDBC connector included:

sudo apt-get install --yes postgresql libpg-java

Prepare a PostgreSQL user who:

• won't be a superuser
• won't be able to create other users
• will be able to create and manage its own databases

sudo su - postgres
createuser -d -S -R myuser

Set the password for myuser

psql -c "ALTER USER myuser WITH PASSWORD 'mypassword';"

Log out of postgres

exit

and come back as myuser

Xvfb

sudo apt-get install --yes xvfb

Xvfb will start as a service every time the machine is booted

sudo wget https://gist.github.com/raw/3953615/eb6f32a9b5735d7d20d7073026d89a39649dff0f/xvfbd -O /etc/init.d/xvfbd
sudo chmod a+x /etc/init.d/xvfbd
sudo update-rc.d xvfbd defaults
sudo service xvfbd stop ; sudo service xvfbd start

ref: https://gist.github.com/raw/3953615/eb6f32a9b5735d7d20d7073026d89a39649dff0f/xvfbd

Tomcat

sudo apt-get install --yes tomcat6

Plug the JDBC connector for PostgreSQL into Tomcat:

sudo ln -s /usr/share/java/postgresql-jdbc3-9.1.jar /usr/share/tomcat6/lib/postgresql.jar

Configure Tomcat to trim all the unneeded and sometimes harmful white-spaces

sudo wget https://gist.github.com/raw/3953615/66e98bb6f472974339766d87d930331dd78ea274/tomcat6_web.xml -O /var/lib/tomcat6/conf/web.xml

ref: https://gist.github.com/raw/3953615/66e98bb6f472974339766d87d930331dd78ea274/tomcat6_web.xml

Force Tomcat to look for the right DISPLAY

sudo wget https://gist.github.com/raw/3953615/c90fd1611e13ec1753e857949c7fa9fbe87d7799/etc_initd_tomcat6 -O /etc/init.d/tomcat6

ref: https://gist.github.com/raw/3953615/c90fd1611e13ec1753e857949c7fa9fbe87d7799/etc_initd_tomcat6

Tell Tomcat that the environment actually provides a graphical server (Xvfb)

sudo wget https://gist.github.com/raw/3953615/57eee1be71f7960aa4c84cee0c65f346ed3d5d46/etc_default_tomcat6 -O /etc/default/tomcat6

ref: https://gist.github.com/raw/3953615/57eee1be71f7960aa4c84cee0c65f346ed3d5d46/etc_default_tomcat6

Make Tomcat reload the new configurations

sudo service tomcat6 restart

Apache and mod_jk

sudo apt-get install --yes apache2 libapache2-mod-jk

Tell the server its name is also www.mydomain.com

echo "123.123.123.123  www.mydomain.com" | sudo tee -a /etc/hosts

where 123.123.123.123 is the real public IP address of the server

Hook up together Apache and Tomcat with mod_jk

sudo wget https://gist.github.com/raw/3953615/0cfbf0cbf669d856bfc54a0087618c6835eba756/tomcat6_server.xml -O /var/lib/tomcat6/conf/server.xml

ref: https://gist.github.com/raw/3953615/0cfbf0cbf669d856bfc54a0087618c6835eba756/tomcat6_server.xml

Another restart in order to reload the new configuration

sudo service tomcat6 restart

Disable mod_jk

sudo a2dismod jk
sudo service apache2 restart

Configure mod_jk

sudo wget https://gist.github.com/raw/3953615/a1fd73a6dc72740b9bfc149c711294b4fc338a1b/jk.conf -O /etc/apache2/mods-available/jk.conf

ref: https://gist.github.com/raw/3953615/a1fd73a6dc72740b9bfc149c711294b4fc338a1b/jk.conf

Configure the AJP13 worker

sudo wget https://gist.github.com/raw/3953615/56f4a30ecfef1c49e97f3f26b8487ad53cce5334/workers.properties -O /etc/libapache2-mod-jk/workers.properties

ref: https://gist.github.com/raw/3953615/56f4a30ecfef1c49e97f3f26b8487ad53cce5334/workers.properties

Re-enable mod_jk and reload the new configuration

sudo a2enmod jk
sudo service apache2 restart

A VirtualHost for our beloved www.mydomain.com

Don't miss the sed part.

• myportal is the name of your application (should be equal to the artifactId, the name of the base directory, the prefix of the name of the databases and so on)
• www.mydomain.com you know it already

sudo bash -c "wget https://gist.github.com/raw/3953615/938f9a0d4eeb13826b50dc2be04d241b88f8bba1/VirtualHost -O - | sed s/FQDN/www.mydomain.com/g | sed s/APPNAME/myportal/g > /etc/apache2/sites-available/www.mydomain.com"

ref: wget https://gist.github.com/raw/3953615/938f9a0d4eeb13826b50dc2be04d241b88f8bba1/VirtualHost

Create the DocumentRoot:

sudo mkdir /var/www/www.mydomain.com
sudo chown -R www-data:www-data /var/www/www.mydomain.com/

Create the directories and symbolic link needed to make Apache serve those assets instead of Tomcat

sudo -u www-data mkdir /var/www/www.mydomain.com/myportal
sudo -u www-data mkdir /var/www/www.mydomain.com/myportal/resources
sudo -u www-data ln -s /var/lib/tomcat6/webapps/myportal/resources/cms /var/www/www.mydomain.com/myportal/resources/
sudo -u www-data ln -s /var/lib/tomcat6/webapps/myportal/resources/plugins /var/www/www.mydomain.com/myportal/resources/

Enable mod_rewrite, the new VirtualHost and reload with the new configuration

sudo a2enmod rewrite
sudo a2ensite www.mydomain.com
sudo service apache2 restart

ImageMagick

sudo apt-get install --yes imagemagick

Final touches

Make sure the server will use the right JDK

sudo update-alternatives --set java /usr/lib/jvm/java-7-openjdk-i386/jre/bin/java
sudo update-alternatives --set javac /usr/lib/jvm/java-7-openjdk-i386/bin/javac

Reboot the server

sudo reboot

When the server is back up and running, point your browser to

http://www.mydomain.com

If everything is fine:

• Apache will redirect your browser to http://www.mydomain.com/myportal/
• Tomcat will return an Error 404 because we don't have deployed Entando

In fact, this is the next part of the guide.

Just keep on reading!

Part 2: how to deploy your Entando based application

This is the official recommended way to deploy an Entando based application in production.

You may find it to be slightly to very different from your own best practices, and your are free to proceed as you wish.

Nonetheless, this way has been tested throughly in a number of deploys and proved itself to be well suited and sometimes also the smartest way to deploy an Entando based application.

Getting Ready

Put the sources of myportal in a proper place, like ~/Work/Deploy, resulting in something like:

$> pwd
/home/myuser/Work/Deploy/myportal
$> ls
buildProperties.xml  buildTasks.xml  build.xml  pom.xml  src

Now edit a few simple configuration files.
The values in the following examples must of course be adapted to your environment:

1. buildProperties.xml

[... ignorable snippet ...]
        <property name="postgres.hostname" value="localhost" />
        <property name="postgres.port" value="5432" />
        <property name="postgres.username" value="myuser" />
        <property name="postgres.password" value="mypassword" />
[... ignorable snippet ...]
       <property name="tomcat.home.path" value="/var/lib/tomcat6" />
[... ignorable snippet ...]

2. src/main/filters/filter-production.properties

Comment out all the # --------------------- Database Configuration: <DBMS> --------------------- lines you find.
Then, uncomment only the group of lines starting with:
# --------------------- Database Configuration: PostgreSQL ---------------------
and ending with:
--------------------- Database Configuration: MySQL ---------------------

Then you can edit the proper properties:

# [... ignorable snippet ...]
profile.application.baseurl.hostname=www.mydomain.com
profile.application.baseurl.port=
profile.application.baseurl.port.separator=
# [... ignorable snippet ...]
profile.tomcat.home=/var/lib/tomcat6
# [... ignorable snippet ...]
#Sample Configuration: PostgreSQL                                             #
profile.database.username=myuser
profile.database.password=mypassword
# [... ignorable snippet ...]

3. (Bonus) src/main/config/systemParams.properties

If you need it (ok, this is actually pretty much inevitable), you can make Entando use ImageMagick for its image processing routines.

# [... ignorable snippet ...]

#
# set this parameter to true if imagemagick is installed on the system and you need to use it
#
imagemagick.enabled=true

# [... ignorable snippet ...]

Preparing the databases

Create now two empty schemas, which Entando will populate with its data later on startup.

$> ant PG-db-create

Done.
No really, it's done.

Preparing the WAR

$> ant WAR-build

If it is the first time you use Maven on this machine, this could start the downloading of half a ton files... but it's perfectly fine and supposed to happen.
When Ant and Maven finish their job and exit without errors, you're done.

Deploying the WAR

This is the way I do it:

• stop tomcat
  sudo service tomcat6 stop
• copy the WAR in /var/lib/tomcat6/webapps
sudo -u tomcat6 ant WAR-deploy
• enter in tomcat land
  cd /var/lib/tomcat6/webapps
• unzip the WAR to get rid of some strange tomcat behaviours about having WARs sticking around, or removing them while it's up and running...
  sudo -u tomcat6 unzip myportal.war -d myportal
• delete the WAR
  sudo -u tomcat6 rm myportal.war
• go up one level
  cd /var/lib/tomcat6
• start tomcat and lurk the logs for problems
  sudo service tomcat6 start && sudo -u tomcat6 tail -f logs/catalina.out
• Beer!

Part 3: how to update your Entando based application

So you've succefully deployed your Entando based application as in Part 2: how to deploy your Entando based application
Days passed by, and it's now time to deploy an update.

Getting Ready

Put the sources of the updated myportal in a proper place, like ~/Work/Deploy, resulting in something like:

$> pwd
/home/myuser/Work/Deploy/myportal
$> ls
buildProperties.xml  buildTasks.xml  build.xml  pom.xml  src

You could decide to use a different setup here, maybe somehing like:

$> pwd
/home/myuser/Work/Deploy/2012-01-01.1650/myportal
$> ls
buildProperties.xml  buildTasks.xml  build.xml  pom.xml  src

So you can keep track of the various deploys in time.
It's up to you.

Also, check - and if needed, edit - the three configuration files as in Part 2: how to deploy your Entando based application

Taking care of the databases

First of all, backup the current database.
You can use ant PG-db-backup but it will replace the database dumps in src/main/db/tar/ so you'll have to deal with it.
I personally use git and create proper local branches to circumvent this and other obvious issues.

Now.

If you have an up-to-date database dump in your updated sources, then:

• if nobody wrote anything in the database of the currently deployed application, then go on and just ant PG-db-full-update away the current database replaceing it with the new dump from src/main/db/tar/.
• if somebody did write anything in the database of the currently deployed application, then keep on reading

If you happen to don't have an up-to-date database dump, then:

• you must have the new data in some other form, right?
  That form is a bunch of SQL queries sitting in src/main/db/update/ or somewhere else, not necessarily on the server
• execute the queries, stopping tomcat if you think is necessary

Taking care of the application

This is even easier:

• backup the application, with something like this:

tar cvzf /home/myuser/Work/Backup/myportal_2012-01-01.1700_webapp.tar.gz /var/lib/tomcat6/webapps/myportal && \
cp /var/lib/tomcat6/conf/Catalina/localhost/myportal.xml /home/myuser/Work/Backup/

• build the new WAR as in Part 2: how to deploy your Entando based application
• stop tomcat
  sudo service tomcat6 stop
• delete the current application

sudo -u tomcat6 rm -rf /vat/lib/tomcat6/webapps/myportal && \
sudo -u tomcat6 rm /var/lib/tomcat6/conf/Catalina/localhost/myportal.xml && \
sudo -u tomcat6 rm -rf /var/lib/tomcat6/work/Catalina/localhost/myportal

• copy the new WAR in /var/lib/tomcat6/webapps
cd <WHERE YOU HAVE THE UP-TO-DATE SOURCES> and sudo -u tomcat6 ant WAR-deploy
• enter in tomcat land
  cd /var/lib/tomcat6/webapps
• unzip the WAR to get rid of some strange tomcat behaviours about having WARs sticking around, or removing them while it's up and running...
  sudo -u tomcat6 unzip myportal.war -d myportal
• delete the WAR
  sudo -u tomcat6 rm myportal.war
• go up one level
  cd /var/lib/tomcat6
• start tomcat and lurk the logs for problems
  sudo service tomcat6 start && sudo -u tomcat6 tail -f logs/catalina.out
• MOAR Beer!