2. Getting Started¶

This chapter is for users who are new to AMPS and want to get up and running on a simple instance of AMPS. This chapter will walk new users through the file structure of an AMPS installation, configuring a simple AMPS instance and running the demonstration tools provided as part of the distribution to show how a simple publisher can send messages to AMPS.

Installing AMPS¶

To install AMPS, unpack the distribution for your platform where you want the binaries and libraries to be stored. For the remainder of this guide, the installation directory will be referred to as $AMPSDIR as if an environment variable with that name was set to the correct path.

Within $AMPSDIR the following sub-directories listed in Table 2.1.

Directory	Description
bin	AMPS engine binaries and utilities
docs	Documentation
lib	Library dependencies
sdk	Include files for the AMPS extension API

Table 2.1: AMPS Distribution Directories

Tip

AMPS client libraries are available as a separate download from the AMPS web site. See the AMPS developer page at http://www.crankuptheamps.com/developer to download the latest libraries.

Starting AMPS¶

The AMPS Engine binary is named ampServer and is found in $AMPSDIR/bin. Start the AMPS engine with a single command line argument that includes a valid path to an AMPS configuration file. You use the configuration file to enable and configure the AMPS features that your application will use. This guide discusses the most commonly-used configuration options for each feature, and the full set of options is described in the AMPS Configuration Reference.

The AMPS server can generate a minimal sample configuration file with the --sample-config option. For example, you can save the sample configuration file to $AMPSDIR/amps_config.xml with the following command line:

$AMPSDIR/bin/ampServer --sample-config > $AMPSDIR/amps_config.xml

Tip

The sample configuration file generated by the server shows a minimal AMPS configuration. The client language distributions include an AMPS configuration file designed to work with the examples included with that client.

The server sample configuration only provides configuration for subscribe/publish use of AMPS, and does not include any persistence for AMPS messages.

The file enables the instance administrative interface (the “Galvanometer”), including the ability to subscribe to topics using a websocket connection from the instance administrative interface.

A production configuration would likely provide persistent event and error logging to a file to allow an operations team to troubleshoot the instance. A production configuration would typically persist monitoring statistics to a file. Such a configuraiton would likely enable additional message delivery features for certain topics, and would also include configuration for high-availability and disaster recovery. The configuration would typically configure AMPS actions to perform routine maintenance.

Once you have a configuration file saved to $AMPSDIR/amps_config.xml you can start AMPS with that file as follows:

$AMPSDIR/bin/ampServer $AMPSDIR/amps_config.xml

The sample configuration file generated by AMPS includes a very minimal configuration. The client language distributions include a sample configuration file that sets up AMPS to work with the samples provided with that client, and the AMPS Configuration Reference contains a full description of the configuration items with sample configuration snippets.

Tip

AMPS uses the current working directory for storing files (logs and persistence) for any relative paths specified in the configuration. While this is important for real deployments, the demo configuration used in this chapter does not persist anything, so you can safely start AMPS from any working directory using this configuration.

Tip

On older processor architectures, ampServer will start the ampServer-compat binary. The ampServer-compat binary avoids using hardware instructions that are not available on these systems.

You can also set the AMPS_PLATFORM_COMPAT environment variable to force ampServer to start the ampServer-compat binary. 60East recommends using this option only on systems that do not support the hardware instructions used in the standard binary. The ampServer-compat binary will not perform as well as ampServer, since it uses fewer hardware optimizations.

If your first start-up is successful, you should see AMPS display a simple message similar to the following to let you know that your instance has started correctly.

AMPS A.B.C.D.973814.e1a57f7 - Copyright (c) 2006-202X 60East Technologies Inc.
(Built: XXXX-YY-ZZT00:26:45Z)
For all support questions: support@crankuptheamps.com

The version numbers and dates will be appropriate for the version that you’ve started.

If you see this, congratulations! You have successfully cranked up the AMPS!

Command Line Options¶

The AMPS server binary supports the following command line options:

Option	Effect
`--verify-config`	Parse and verify the specified configuration file, then exit.
`--sample-config`	Produce a minimal AMPS config.xml file to standard output, then exit.
`--dump-config`	Process the specified configuration file, resolving any Include directives and expanding environment variables. Dump the resulting file to standard output.
`--version`	Print the AMPS version string, then exit.
`--help`	Print usage information for the commandline options accepted by the ampServer program, then exit.
`--daemon`	Run AMPS as a daemon process.
`-D<variable>=<value>`	Set the specified environment variable to the specified value when running the AMPS process. AMPS accepts any number of `-D` options. For example, to set the variable `AMPS_PATH` to `/mnt/fast/AMPS` use the command line option `-DAMPS_PATH=/mnt/fast/AMPS`

Table 2.2: ampServer command line options

Admin View of the AMPS Server¶

When the admin server is enabled in the configuration, you can get an indication as to whether AMPS is running or not by connecting to its admin port with a browser at http://<host>:<port>/amps where <host> is the host the AMPS instance is running on and <port> is the administration port configured in the configuration file.

When successful, a hierarchy of information regarding the instance will be displayed. If you’ve started AMPS using the sample configuration file, try connecting to http://localhost:8085/amps. For more information on the monitoring capabilities, please see the AMPS Monitoring Reference Guide, available from the 60East documentation site at http://docs.crankuptheamps.com/.

Interacting with AMPS Using Spark¶

AMPS provides the spark utility as a command line interface to interacting with an AMPS server. spark provides many of the capabilities of the AMPS client libraries through this interface. The utility lets you execute commands like 'subscribe', 'publish', 'sow', 'sow_and_subscribe' and 'sow_delete', described elsewhere in this Guide.

spark is a Java application, and requires a JRE version 1.7 or later to run.

Applications that use AMPS use one of the client libraries, available from http://www.crankuptheamps.com/develop. The spark utility supports a subset of AMPS functionality, and is most often used for troubleshooting, ad hoc testing, or light scripting.

For example, to simply test connectivity to an AMPS server, spark provides a ping command. This command simply makes a connection to the server using the specified parameters, and reports whether that connection succeeded or failed. You can run the command as follows, where the server parameter is the address and port of the AMPS server, and the type parameter is the message type to use for this connection:

$ ./spark ping -server localhost:9007 -type json
Successfully connected to tcp://user@localhost:9007/amps/json

If spark encounters an error while connecting to AMPS, spark reports that error on the command line.

You can read more about spark in the Spark Section of the AMPS User Guide appendix. Other useful tools for troubleshooting AMPS are described in the AMPS Utilities Guide.

Next Steps¶

The next step is to configure your own instance of AMPS to meet your messaging needs. The AMPS configuration is covered in more detail in AMPS Configuration Reference Guide

After you have successfully configured your own instance, there are two paths where you can go next.

One path is to continue using this guide and learn how to configure, administer and customize AMPS in depth so that it may meet the needs of your deployment. If you are a system administrator who is responsible for the deployment, availability and management of data to other users, then you may want to focus on this User Guide first.

The other path introduces the AMPS Client APIs. This path is targeted at software developers looking to integrate AMPS into their own solutions. 60East provides client libraries for C, C++, C#, Java and Python. These libraries are available for download from the 60East website. The website also includes evaluation kits designed to help programmers quickly get started with AMPS. For developers, the basic functionality of the AMPS server is explained in this User Guide. The Developer Guides and API documentation explain how to use that particular client library to create applications that use AMPS functionality.

Table Of Contents

Related Topics