Month: December 2020

Hosting AEM on Azure with Ubuntu

/ ace / Leave a comment

The two primary components of AEM are the author and publisher instances. Both can be downloaded from Adobe as either war or jar.

This guide is to setup a dual server non-production instance for testing or developing.

AEM comes in two flavours: self hosted or cloud SDK. Both of these have a quickstart jar file and both can be used in this guide. The differences are:

  1. self hosted requires a license file. Cloud SDK does not.
  2. self hosted comes with a default WKND website and replication by default. Self hosted requires setting this up if required.

Step 1: install java on your local machine.

Skip this step if you already have the license.properties file, or you are using the cloud SDK, or you already have java installed.

In theory you should have oracle java jre version 11 to create the license file. However, it will work with oracle java 8 also. It may or may not work with non oracle java.

To test your local installation, open a terminal window or command prompt and type “java -version”.

Step 2: get hold of jars and generate license file.

This is the hardest step, unless you happen to be a premium Adobe partner. You will need to write to Adobe with a business case for being allowed to setup a dev environment in order to learn AEM basics. They will send you a link to the jar file, along with a key.

Once you have the quickstart jar (e.g. AEM_6.5_Quickstart.jar), you need to run it locally as is on your local windows, mac or linux machine. Do this by double clicking on it. It will take some minutes to startup, then will prompt you for your key. It will then generate a license.properties file in the same dir as the jar.

Note, running the jar will create a directory called crx-quickstart, which will be around 2GB. Delete this when you are finished.

Step 3: provision 2 VMs in Azure.

One will be for author and one for publish, but you can also put them on the same box and give it more ram.

  1. login to your subscription (or create a free one) at https://portal.azure.com/
  2. Create “new” resource
  3. Search the marketplace for ubuntu
  4. select “Ubutu Server 20.0.4 LTS” from canonical or your preferred distro and version.
    1. create a new resource group or use an existing one (just for reporting)
    2. give it a name like “author1” and “publish1”
    3. Chose a cheap region close to you. Some regions are twice the price of others. See https://azureprice.net/Region for price comparison.
    4. leave availability zone default
    5. For spot instance I go with no if you want it available any time.
    6. for size the cheapest viable server is B2s with 2 vCPU and 4GB ram at £25/m. B instances are for servers which are idle most of the time, i.e. when no devs are using the served pages.
    7. For administration type I would always select SSH public key over password.
    8. chose your username (same one for both boxes). Dont use a generic name such as “admin” or a first name such as “bob” or “david”, these are too easily guessed.
    9. if you dont have an SSH key handy, you can let it generate the pair for the first box, the re-used the generated one for the second.
    10. Inbound port rules: Unless you have a fixed IP VPN, or a VLAN, you will probably want to open SSH (22) to the world so you can administer the box. We can change the ports later. Note: this is using Azure firewall, not Ubuntu’s firewall.
  5. Disks
    1. select standard SSD with default encryption.
    2. Hit “create and attach a new disk”
    3. default name
    4. source type = None
    5. select Standard SSD (again), 32GB or more, hit ok.
  6. Networking
    1. choose same or new virtual network.
    2. default subnet
    3. new public ip for each
    4. NIC security group: basic
    5. inbound ports: SSH (22)
    6. accelerated networking / load balancing not applicable.
  7. Management (leave all default)
  8. Advanced. you can choose Gen 2 (EFI), but Gen 1 is arguably more common.
  9. Tags. Add tags you like, e.g. who created it, what its for, when it should be killed etc.
  10. Hit Create!

Step 4: setup DNS (optional)

You will now have 2 IPs allocated by Azure for your two VMS. These are shown in Azure in the info page for the VM.

If you own a domain, you can now create two A records such as author.yourdomain.com and publish.yourdomain.com with those ips.

Step 5: import the key.

windows

If you are on windows, and you allowed Azure to generate they keys, you need load the key you downloaded into puttygen and convert it into a ppk private key, then load this key into pageant.

Create a new putty profile with host name of yoruname@publish.yourdomain.com or yourname@yourserversIP and one for author following the same pattern.

Linux / Mac

If you have linux or mac, you need to copy the private key file int tour ~/.ssh/id_rsa file and make sure it has the right permissions. There are many guilds on this process.

Step 6: download java

Go to https://www.oracle.com/java/technologies/javase-jdk11-downloads.html and download the deb package for linux x64 (the tar.gz would also work). You have to accept license etc. Don’t install openJDK, which is easy but is not supported by Adobe, If you try it and it works let me know.

Step 7: upload everything to both servers.

You will need to upload the java deb package (or tar.gz), the quickstart Jar and license.properties (if using the non cloud sdk)

The easiest way to do this using filezilla. create a new filezilla profile with the following settings:

Host: your server DNS name or ip
Protocol: SFTP
login type: Key File
user: your user name you entered in Azure host config
Key file: select the ppk (windows) or private key rsa/pem file (linux/macos)

open the new site and you should see the home directory of your user. Upload the 3 files to both your servers.

Step 8: Setup java on your new instance(s)

ssh into each of your new servers, and do the following:

  1. $ sudo apt-get update
  2. $ sudo apt-get dist-upgrade -y
  3. reboot if necessary.
  4.  sudo dpkg -i jdk-11.0.9_linux-x64_bin.deb
  5. either edit /etc/profile (to setup java for all users) or specific users ~/.profile and add the following at the end (change the path to match your java version:
    1. export JAVA_HOME=”/usr/lib/jvm/jdk-11.0.9/”
    2. PATH=$JAVA_HOME/bin:$PATH
  6. open a new shell and test java with “java -version” and you should see something like this:

java version “11.0.9” 2020-10-20 LTS
Java(TM) SE Runtime Environment 18.9 (build 11.0.9+7-LTS)
Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.9+7-LTS, mixed mode)

Step 9: setup and run AEM

  1. create a new user (you can also create it the regular way with just “sudo adduser aem”)
    1. $ adduser –disabled-password –gecos “” –shell /bin/bash
  2. switch to new user:
    1. sudo su – aem
  3. If you didnt add java paths to the global /etc/profile then you need to add it to this users /home/aem/.profile
  4. copy jar and license to aem:
    1. $ mkdir author (publish on second server)
    2. $ cd author (publish on second server)
    3. $ cp /home/youruser/AEM*.jar .
    4. $ cp /home/youruser/*.properties .
  5. rename the jar. Note: some guides say it should start with “aem”, some say it should start “cqx” where x is a number.
    1. mv AEM_6.5_Quickstart.jar aem-author-p4502.jar (on author server)
    2. mv AEM_6.5_Quickstart.jar aem-publish-p4503.jar (on publish server)
  6. In theory, you should now be able to run the jar with this:
    1. $ java -XX:MaxPermSize=256m -Xmx2048M -jar aem-author-p4502.jar
    2. $ java -XX:MaxPermSize=256m -Xmx2048M -jar aem-publish-p4503.jar
  7. you can also change the port and start in background:
    1. $ nohup java -XX:MaxPermSize=256m -Xmx2048M -jar aem-author-p8080.jar &
    2. $ nohup java -XX:MaxPermSize=256m -Xmx2048M -jar aem-publish-p8080.jar &
  8. check what is happening:
    1. $ tail -f /home/aem/publish/crx-quickstart/logs/error.log
    2. $ tail -f /home/aem/publish/crx-quickstart/logs/stdout.log

Alternative method to run the jar.

There are several scenarios where running the jar fails, but unpacking and running the start script works.

  1. $ java -jar *.jar -unpack
  2. $ /home/aem/publish/crx-quickstart/bin/start

Step 10: view the console/site

You have three options:

  1. open up ports 4502/4503 to the world on the author and publisher Azure firewall respectively (insecure)
  2. open the above ports but only to your fixed IP (secure)
  3. use a ssh tunnel (secure)

By default, both author and publisher do not have SSL, and only run http, not https. So any passwords are visible. A later article will look at how to enable SSL and port 443.

Below are example settings for opening port 4502 (author) and 4503 (publisher) to world:

If you want to open the ports only to your local machine, you can use a ssh tunnel. In putty it will look like this:

Here I am mapping the remote port 4502 to 4512 on my local machine.

Do the same for the other server on 4503

Now you can hit the UI on http://localhost:4512 and http://localhost:4513

However, replication will not work unless you setup a rule to allow this between servers via Azure firewall, or use the vlan ip if you put both servers on the same vlan.

Next steps:

  1. configure SSL in both instances, and run them on port 443.
  2. turn the start/stop script into services which start on boot.
  3. setup and test replication between author and publisher.
  4. setup monitoring to alert you if either goes down.