Alfresco Boxes – State of the Art Automation to create your alfresco environment

Hi folks, my second post on my new Alfresco blog could not be about a better topic, let me start by telling you that Alfresco Boxes rocks and it just makes me proud to be a personal friend and colleague of its creator, Maurizio Pillitu. It was never so easy to setup and run a fully featured alfresco environment.

Alfresco Boxes is a community-driven effort, currently in experimental phase, not supported and not guaranteed by Alfresco. As usual, if you choose to use this technology and you run into problems, please let us know so we can quickly change the project name and pretend that is someone else’s fault. :-).

Jokes apart, If you want to create your alfresco environments using a fast, intelligent, reusable, automated way then Alfresco Boxes is what you’re looking for.  Let’s start jamming with some boring but necessary theory. I’ll promise i wont take it very far and you’ll be able to start to experiment all of this real quickly.

On the github project page (https://github.com/maoo/alfresco-boxes) Maurizio  starts to define Alfresco boxes as :

“A collection of utilities for Alfresco VM provisioning and deployment that works with either Packer, Vagrant or Docker; the deployment and installation logic is provided by chef-alfresco.”

Packer is a free (open-source ) tool for creating identical machine images for multiple platforms from a single source configuration. It’s easy to use and automate the creation of any type of machine image. It embraces modern configuration management by encouraging you to use automated scripts to install and configure the software within your Packer-made images. Packer brings machine images into the modern age, unlocking untapped potential and opening new opportunities. Out of the box Packer comes with support to build images for Amazon EC2, DigitalOcean, VirtualBox, and VMware.

Vagrant does the same as packer does, only using a specific file extension (.box) that contains all files needed by a local provider (VMWare or VirtualBox) to run the VM; check vagrantcloud and vagrantbox.es to get an idea of the pre-packaged boxes available that you can re-use on your own projects.

Docker is a linux kernel module that provides virtualization “super-powers”. Docker introduces the concept of container, which is a virtualization of the host operating system resources. Docker is a server that can start,stop and kill containers, so its basically a virtualization server with a new approach to the virtualization paradigm. As with Vagrant, Docker delivers an Image Index (Alfresco images soon to come)

In a nutshell you can use either one of the 3 technologies above (depending on what you want to achieve) to automate your alfresco deployment strategy and the creation of your alfresco environments. On this blogpost i will focus exclusively Packer but, from a technical standpoint, the 3 approaches have one thing in common… “Chef Alfresco”.

Chef Alfresco is a Chef Cookbook (a collection of build tasks) that defines the installation steps needed to deliver a fully working Alfresco instance on a given VM. If you’re not familiar with Chef, it is a Build Automation tool that uses a agent-client/server architecture to process and execute build tasks, so called recipes.

Chef Alfresco depends on other cookbooks, such as artifact-deployer, that fetches artifacts from remote Apache Maven repositories and defines default values (i.e. Maven artifact coordinates) for all artifacts (WARs, ZIPs, JARs) involved in the Alfresco deployment process; it also depends on other third-party recipes that install the DB (MySQL), Servlet Container (Tomcat) and transformation tools (ImageMagick, LibreOffice, swftools). If you want to check the full list of dependencies, check the Berkshelf file of alfresco-boxes.

 ! OK, ITS TIME TO GET BUSY, LET’S TRY IT !

Now that you know the basics of the theory its time to have a real taste on the Alfresco Boxes technology. Following is a list of step by step actions and a how to video that will guide you on how to use all of this in a simple way. First think you need is to check if you have the prerequisites necessary to proceed.

• Make sure Ruby is installed ( test with ruby -v) if not install it as per Ruby Installation Url.

MacOS Users : To have Ruby installed, the best way is to install XCODE, preferable the latest version.

Now that the prerequisites are in place, lets start to install Alfresco boxes and build our first Alfresco vmware in a automated-way. The following instructions focused on the Packer approach. You find detailed documentation on other variants such as Docker or Vagrant on Github Alfresco Boxes project.

Installing Alfresco Boxes

1 – Download and install Packer.

• Go to http://www.packer.io/downloads.html and download the appropriate version for your operating system.

• Unzip the packer package and make sure the unziped location is part of your local path.

  • For Linux/MacOs : export PATH=<your_path_to_packer>:$PATH

• Test if packer is installed and available on your system by typing the following command :

  • # packer -v

2 – Download and install virtualBox

• Go to https://www.virtualbox.org/wiki/Downloads and download the appropriate version for your OS.

3 – Checkout the Alfresco Boxes git project.

• Checkout alfresco boxes by running the following command on a terminal (you need to have git installed, if you don’t know about git, now its a good time to learn it and start using it )

• # git clone -b alfresco-boxes-0.5.1 https://github.com/maoo/alfresco-boxes.git

The git clone command created a alfresco-boxes folder on your system and downloaded all the projects content for the specific branch being checked out.

4 – Local configuration adjustments

4.1 Change directory to alfresco-boxes/packer/

# cd alfresco-boxes/packer/

4.2 Edit file precise-alf421.json to choose an IP that can be bridged to one of your host Network Interfaces:

{
  "type": "shell",
  "execute_command": "echo 'vagrant' | sudo -S sh '{{ .Path }}'",
  "inline": ["/tmp/static-ip.sh <your_ip_range_here>.223 192.168.1.1 255.255.255.0"]
}

4.3 Edit the vbox-precise-alf421/data_bags/maven_repos/private.json 

Edit this file to set your access credentials to artifacts.alfresco.com ( access can be requested by Alfresco Customers via the Alfresco Support Portal).

P.S. – If you don’t have credentials to artifacts.alfresco.com you can still test alfresco-boxes  using the Community edition: change the alfresco-allinone.json version attribute from 4.2.1 to 4.2.f

{
  "id":"private",
  "url": "https://artifacts.alfresco.com/nexus/content/groups/private",
  "username":"your_user",
  "password":"your_password"
}

You can optionally use your Maven encryped password and set your Maven Master password in precise-alf421.json:

"maven": {
  "master_password":"{your_mvn_master_password}"
}

4.4 Generate the Virtual Machine box:

cd alfresco-boxes/packer/vbox-precise-421
packer build -only virtualbox-iso precise-alf421.json

This will create a output-virtualbox-iso/.ovf and output-virtualbox-iso/.vdmk, ready to be imported into VirtualBox. You should now have a fully functional version of Alfresco with everything installed and ready to run.

The user/password to login (and check the local IP – ifconfig – that is assigned by DHCP) is vagrant/vagrant.

5  Virtual Machine (Ubunto) Notes

Open a terminal with a ssh connection to your virtual machine.

# ssh vagrant@<your_vm_ip>

5.1 – Start by changing/setting the root password

#sudo sh

# passwd root

5.2 Change tomcat7 password

# su –

# passwd tomcat7

5.3 Take a note of your usernames and passwords :

Make notes of your usernames and passwords, you will need them later.

root | <your_root_password>
tomcat7 | <your_tomcat7_password>

5.4 Tomcat 7 locations

CATALINA_BASE=/var/lib/tomcat7
CATALINA_HOME=/usr/share/tomcat7

5.5 To start | stop tomcat ( use sudo and tomcat7)

# sudo service tomcat7 start|stop|restart|status

5.6 Tomcat logs directory

/var/logs/tomcat7

5.7 Alfresco and Alfresco Share logs directory

/var/lib/tomcat7

5.8 Alfresco shared dir location

/var/lib/tomcat7/shared

5.9 Alfresco admin user 

( admin | admin )

Hope you enjoyed the article on its current status, i will be posting a step by step video to illustrate the most relevant steps for your guidance on the near future , so stay tuned.

Love, Passion, Unity and OpenSource can take us further. We’re together, thanks for reading.