5. Customizing your instance

Customizing your instance is the most complicated part of creating a custom elastic image. You need to install the packages that are prerequisites for Bamboo onto your instance (if you didn't choose the Elastic Bamboo Stock images as your base AMI), add your customizations, deploy Bamboo onto your instance and set up an EC2 environment on your instance.

5.1 Installing Bamboo prerequisite packages

If you selected Atlassian's AMI as your base AMI in '2. Selecting an Existing AMI', you can skip this step and go to '5.2 Adding Customizations' as this image has been pre-configured for Bamboo. If you have selected a different AMI, you will need to install the following packages onto your instance using the commands shown below:

Amazon EC2 API tools

wget http://s3.amazonaws.com/ec2-downloads/ec2-api-tools.zip
unzip ec2-api-tools.zip
mv ec2-api-tools-* /opt/ec2-api-tools

Note: if your distribution already contains ec2-api-tools package, you can install it instead.

Java JRE

You need to install a JRE (or JDK) on your instance to be able to run the agent. The preferred way of doing this is to install a package that came with your distribution.  For a list of supported JREs, see supported platforms.

5.2 Adding user customizations to your instance

Adding your own customizations is quite a simple process, once you have made it this far.

To add user customizations to your instance:

1. Log into your elastic instance (as previously described in '4. Accessing your Instance').
2. Once you have logged into your elastic instance, you can treat it as a standalone machine and install anything you want. For example, if you want to install Tomcat on an Ubuntu instance you would run 'sudo apt-get install tomcat6', configure it, ensure that your startup scripts are in place, etc, just as you would when installing Tomcat on a standalone machine.
   Please note however, you cannot customize the operating system of a running instance. If you want to create an instance with a customized operating system (e.g. Ubuntu), you will need to select an AMI with that operating system installed (as previously described in '2. Selecting an Existing AMI').
3. Everything that you install will be saved in snapshot image created at the end of these instructions (see '6. Creating an Image of your Customized Instance'). Any instances started from this image will have all of your user customizations automatically installed.

5.3 Deploying Bamboo onto your instance

Once you have installed the Bamboo pre-requisites on you instance and added your customizations, you can deploy Bamboo elastic bootstrap files onto your instance.

5.3.1 Creating Bamboo user

First, you need to create a 'bamboo' user on your instance by running the following command:

useradd -m bamboo

5.3.2 Downloading agent installer to the instance

Then, install Bamboo Agent binaries as described below. In this case we're using image version 2.2, you should use the latest version available at https://maven.atlassian.com/content/repositories/atlassian-public/com/atlassian/bamboo/atlassian-bamboo-elastic-image/.

imageVer=2.2
wget https://maven.atlassian.com/content/repositories/atlassian-public/com/atlassian/bamboo/atlassian-bamboo-elastic-image/${imageVer}/atlassian-bamboo-elastic-image-${imageVer}.zip
sudo mkdir -p /opt/bamboo-elastic-agent
sudo unzip -o atlassian-bamboo-elastic-image-${imageVer}.zip -d /opt/bamboo-elastic-agent
sudo chown -R bamboo /opt/bamboo-elastic-agent
sudo chmod -R u+r+w /opt/bamboo-elastic-agent

5.4 Instance configuration

At this stage, you should have a customized instance with Bamboo deployed onto it. The last step in creating a customized instance is to set up an EC2 environment on your instance. Carry out the following steps to set this up:

1. Run the following command on your instance to set permissions on the bamboo user directory:
   
   

   chown -R bamboo:bamboo /home/bamboo/
   

2. Configure path variables
   Create a file profile.sh in your instance's /mnt directory. This file contains the default Elastic Bamboo path configuration settings, as seen below:

   export JAVA_HOME=<path to JRE used to start the agent>
   export EC2_HOME=<location of your EC2 tools installation>
   export EC2_PRIVATE_KEY=/root/pk.pem
   export EC2_CERT=/root/cert.pem
   export PATH=/opt/bamboo-elastic-agent/bin:$EC2_HOME/bin:$JAVA_HOME/bin:$M2_HOME/bin:$MAVEN_HOME/bin:$ANT_HOME/bin:$PATH
   

   If all of the tools on this page were installed in recommended locations, no changes are required. Otherwise, you can update the file as required.
   Once profile.sh is correctly customized for your instance, you need to copy it to the /etc/profile.d directory by running the following command on your instance in the /mnt directory:

   mv profile.sh /etc/profile.d/bamboo.sh

3. Configure the Bamboo agent to start up automatically with the instance by sourcing Bamboo's /opt/bamboo-elastic-agent/etc/bambooInstanceStartup.sh file in SysVinit or systemd.

   Alternatively, you can use the AWS cloud-init startup scripts. To do that, create a script like the one below and add it to your cloud-init configuration in /var/lib/cloud/scripts/per-instance/bamboo-agent-start:

   #!/bin/sh
   
   # Bamboo agent startup
   . /opt/bamboo-elastic-agent/etc/bambooInstanceStartup.sh
   
   exit 0

   For more information, go to Run commands on your Linux instance at launch in the Amazon Elastic Compute Cloud documentation.

4. Ensure the bamboo user can write to and execute from /tmp. Validate if noexec option is NOT set on/tmp mountpoint.
   If your security policy enforces you to use noexec as a mount option in /tmp, you can alternatively specify a different java.io.tmpdir during your agent startup:

   $ cat /opt/bamboo-elastic-agent/bin/runStartupScripts.sh
   #!/bin/sh
   
   echo Running startup scripts...
   
   bambooAgentBin=$(cd -P -- $(dirname $0) && pwd)
   
   #
   # custom -Djava.io.tmp to bypass /tmp noexec option
   #
   java -Djava.io.tmpdir=/home/bamboo -cp $bambooAgentBin/*installer*.jar com.atlassian.bamboo.agent.elastic.startup.RunStartupScripts 2>&1 | tee -a /tmp/BambooStartupLog.log

5. Final settings and cleanup
   Finally, create a Bamboo welcome screen and clean up keys on your instance by running the following command:
   
   

   cp /opt/bamboo-elastic-agent/etc/motd /etc/motd
   echo bamboo-<x.x.x>  >> /etc/motd
   rm -f /root/firstlogin /etc/ssh/ssh_host_dsa_key /etc/ssh/ssh_host_dsa_key.pub
   /etc/ssh/ssh_host_key /etc/ssh/ssh_host_key.pub /etc/ssh/ssh_host_rsa_key
   /etc/ssh/ssh_host_rsa_key.pub /root/.ssh/authorized_keys
   touch /root/firstrun
   

   where <x.x.x> is the Bamboo version you are running (e.g. 4.1.2).
   
   

6. Now, follow the instructions from section "Creating an image of your Customized Instance" to create an AMI.

7. Start the image from Bamboo. The agent should come up and download all necessary data to the EC2 instance.
   
8. Run /opt/bamboo-elastic-agent/bin/prepareInstanceForSaving.sh.
9. Now, follow the instructions from section "Creating an image of your Customized Instance" to create an AMI. That's it, the newly created AMI contains everything you need to start Bamboo Agents.

Note: if you started your instance from Bamboo right at the start, instead of steps 5 & 6, you can just run:

su -c /opt/bamboo-elastic-agent/bin/bamboo-elastic-agent - bamboo