atlas-run

This page describes the shell script atlas-run, part of the Atlassian Plugin SDK.

Basic usage

 atlas-run [options] - Runs the application with your plugin installed. (Runs mvn amps:run.) Interpreted parameters: version, container, http-port, ajp-port, context-path, server, jvmargs, log4j, test-version, sal-version, rest-version, plugins, lib-plugins, bundled-plugins, product.

Parameters

This shell script supports some interpreted parameters, specified below. All other parameters are passed straight through to Maven.

Explaining the table columns:

  • 'Full Parameter' and 'Shortened' - Some parameters allow you to choose a full or a shortened version of the parameter, others just support the full version.
  • 'Accepts a Value?' - 'Yes' means that you should specify a value in addition to the parameter, e.g. for the 'version' parameter you should specify the version number. 'No' means that the parameter does not accept a value.

Interpreted parameters:

Full Parameter

Description

--version

Version of the application to run. Default is RELEASE. Examples:

  • 3.1
  • 3.1-m7

Shortened: -v

--container

Container to run in. Default is tomcat7x. Other available values are tomcat5x, resin3x and jboss42x.

Shortened: -c

--http-port

HTTP port for the servlet container. The defaults are as described in the SDK overview. You may need to change this if you already have a process listed for the default port, such as when you want to bring up two instances of Confluence.

Shortened: -p

--ajp-port

AJP port for the servlet container. The defaults are as described in the SDK overview. You may need to change this if you already have a process listed for the default port, such as when you want to bring up two instances of Confluence.

Shortened: -ajp

--context-path

The application context path. You will need to include the leading forward slash. For example, if your application is running at http://localhost:1990/confluence then you should enter /confluence.

To run your application in the root web application context (eg. http://localhost:1990), then you should enter ROOT.

--server

Host name of the application server. The default is localhost.

--jvmargs

Additional JVM arguments if required.

--log4j

Log4j properties file.

--test-version

Version to use for test resources. Default is LATEST.

--sal-version

Version of SAL (Shared Access Layer) to use.

--rest-version

Version of the Atlassian REST module to use.

--plugins

A list of plugin artifacts, separated by commas, in the form GROUP_ID:ARTIFACT_ID:VERSION. Version is optional. Default is LATEST. These plugins will be installed into your local version of your plugin's host application.

--lib-plugins

A list of lib artifacts, separated by commas, in the form GROUP_ID:ARTIFACT_ID:VERSION. Version is optional. Default is LATEST. Use this to add additional JARs into your /lib folder.

--bundled-plugins

A list of bundled plugin artifacts, separated by commas, in the form GROUP_ID:ARTIFACT_ID:VERSION. Version is optional. Default is LATEST. These plugins will be loaded as bundled plugins in your local version of your plugin's host application.

--product

The application to launch with the plugin. You might use this if your plugin is written for one application (as specified in the POM) but you want to install the plugin into another application.

All above accepts a value.

Since the latest update of the SDK tomcat7 is now the default. In order to run Jira 5 plugins use the --tomcat6x parameter.

Getting help

The shell script will display some help text if you enter one of the following as the first argument:

  • -?
  • -h
  • help
  • -help
  • --help

For example:

1
2
atlas-run -?
atlas-run -help

Examples

Running a plugin in an application

Say you want to install and run your plugin in your host Atlassian application. Go to the plugin's project directory (where you created the plugin) and type:

1
2
atlas-run

Note that the above shell script will work for any host application, including Confluence, Jira, etc. The script will determine the application, based on your plugin's specifications.

Specifying a version of the application

Say you want to run your plugin with Confluence 2.10.3. Go to the plugin's project directory (where you created the plugin) and type:

1
2
atlas-clean
atlas-run --version 2.10.3

Say you want to run your plugin with Jira 4.0 snapshot. Go to the plugin's project directory (where you created the plugin) and type:

1
2
atlas-clean
atlas-run --version 4.0-SNAPSHOT

Running atlas-clean will clear the previous version of the host application from your build output directory. You only need to do this if the previous application version was different from the one you need now.

Specifying a context path

By default, the host application will run with a context path named after the name of the product. For example, Jira runs with a context path of /jira and Confluence runs with a context path of /confluence. You can specify a custom context path like this:

1
2
atlas-clean
atlas-run --context-path /anotherpath

To run the application in the root web application context (for example, you want to access Jira at the URL http://localhost:2990 with no context path), then specify a value of ROOT like this:

1
2
atlas-clean
atlas-run --context-path ROOT

Specifying an application server (container)

Say you want to run your plugin with Confluence 2.10.3 and JBoss 4.2.x. Go to the plugin's project directory (where you created the plugin) and type:

1
2
atlas-run --version 2.10.3 --container jboss42x

Specifying a version of SAL

Say you want to run that plugin but with Confluence 2.10.3 and SAL 2.0.5:

1
2
atlas-run --version 2.10.3 --sal-version 2.0.5

Running your plugin in multiple applications

Say you want to run that RefApp plugin in multiple applications simultaneously. In three separate tabs in your terminal (command window):

  • Type the following to run the plugin in the RefApp:

    1
2
    atlas-run

  • Type the following to run the plugin in Confluence:

    1
2
    atlas-run --product confluence --version 3.0-m9

  • Type the following to run the plugin in Jira:

    1
2
    atlas-run --product jira --version 4.0-SNAPSHOT

Working with the SDK

Rate this page: