Explore the Installed SDK and the atlas Commands
You should understand the basic contents and functions of the SDK before you develop your first add-on. On this page, you get a summary of the SDK contents, a very brief intro to Apache Maven, and you run an Atlassian application through the SDK. The following topics are covered:
Step 1: Browse the SDK contents and get introduced to Maven
Maven is a popular tool and you may already be using it. You don't need to be a Maven expert to use this tutorial. You do need to understand some Maven basics to develop with the SDK. Examine the contents of the SDK installation:
- Navigate to the directory where the Atlassian SDK (the ATLAS_HOME) was installed.
Not sure where the SDK was installed? Use the
atlas-versioncommand. If you are on a Mac or other Linux system you may need to preface your command with
List the contents of the
The SDK contains the following directories:
Contains the Apache Maven 2 installation. Maven is a popular build management tool. Atlassian built a suite tools around Maven called the Atlassian Maven Plugin Suite (AMPS). These tools automate many add-on development tasks.
Contains command-line wrappers for the most common AMPS calls. All of the commands start with the
In this tutorial, you do all your development with the wrapper commands. This is the typical case. Only very rarely, and then only for very advanced techniques, should you need to work with AMPS directly.
Contains code repositories that the Atlassian SDK is dependent on. This directory is prepopulated during the SDK installation.
- Take some time to list the contents of each of the three sub-directories.
Maven relies on the ability to navigate to external repositories URLs and obtain source packages required by your code. When you build an add-on such as a plugin using the SDK's
atlas- commands, Maven is behind the scenes retrieving the latest Atlassian source files from Atlassian's public repositories. Atlassian preconfigures the location of these repositories in the
Step 2: (Optional) Configure a <proxy> in the Maven
If you're doing your development behind a corporate firewall, you may need to connect to the Internet through an HTTP proxy. If you know you do not have a firewall, skip this procedure. If you know your company requires you to use an HTTP proxy, you need to configure proxy settings in the
ATLAS_HOME/apache-maven/conf/settings.xml file. Do the following:
- Ask your system administrator to provide you with the following information:
- Edit the
ATLAS_HOME/apache-maven/conf/settings.xmlfile in your favorite editor.
- Locate the
- Uncomment the
proxyelement and add the values provided by your system administrator.
When you are done, the element looks similar to the following:
- Close and save the file.
settings.xmlfile, you may encounter problems resolving dependencies required by the SDK commands. To prevent these problems, add the following
<pluginRepository>block to your local
Step 3: Try an atlas command
At this point, you've configured your environment and you are set to begin developing. This tutorial shows you how to add a very simple
helloworld plugin to JIRA. Before you begin writing code, you should use an
atlas command to run JIRA in standalone mode. You use the atlas-run-standalone command to start JIRA.
If you haven't already done so, open a command window and do the following:
Navigate to the root of your drive (Windows) or home directory (Linux).
Create a directory called
Change directory to your newly created directory.
Start latest version of JIRA on default port of 2990, by entering the following:
After the command completes successfully you see a message similar to the following:
The output message tells you the URL where JIRA was started.
- Open a browser and enter the JIRA URL.
You should see the URL for your installation displayed in the run output. For example, you might see
http://localhost:2990/jiradepending on your environment. On successful launch, the browser displays the JIRA login page.
adminfor both the username and password.
Your browser displays the JIRA dashboard:
You'll notice in the Admin section the License that you are running is a
Test license for plugin developers.
Go behind the scenes of atlas-run-standalone
When you issue the
atlas-run-standalone command, it creates a directory called
amps-standalone in the current directory – in this case
JIRA runs as a Tomcat web application on your
localhost — the system on which you issue the command. So, the command actually runs a Maven build on your system. This build
- creates a directory called
amps-standalone/targetin the current
- downloads the latest JIRA product files to your machine
- downloads any dependencies JIRA needs to run this version of JIRA
- builds the JIRA application
- creates a Tomcat 6 container
- deploys JIRA in the container
amps-standalone/target/jira-5.0.log file contains the details such as the environment variables set and used during this process. You'll notice from this log file that the JIRA test instance relies on an HSQL database. You would never use an HSQL database in a production system.
Step 4: State is saved between runs
When you run a standalone instance, you can make changes in the instance. The system remembers what you do between sessions. At this point, you should still have your standalone JIRA instance up and running. Make sure you are logged in and do the following:
- Locate the Admin section on Dashboard.
- Choose the create new link from the Projects section.
The system opens the Create New Project page.
- Name your project
Test Projectand give it a key of
When you are done, the dialog looks similar to the following:
- Click Add to add the project.
Your standalone JIRA now has a TEST project. Test what happens to the project when you restart this standalone instance.
- Return to the command line where you started JIRA.
- Gracefully shutdown JIRA by pressing CTRL-Z (Windows) or CTRL-D (Linux).
- Browse to the default JIRA URL (
http://myhost.local:2990/jira or http://localhost:2990/jira)with your browser.
Your browser should inform you that it could not get a connection to the server.
- Return to the command line (DOS prompt for Windows users).
- Make sure you are in the
Restart JIRA standalone.
- Log back in and locate your project.
The standalone instance has retained the data you created between restarts. This can be very useful when testing. You'll learn more about this later.
You can use the
atlas-run-standalone command to run a particular version of a product. This is useful if, for instance, you want to test your code on an earlier version of JIRA or Confluence. Review the command's reference page and try running an earlier version of JIRA.
At this point, you have some basic understanding of the SDK. Enough to go ahead in the next tutorial section to create your own plugin project.