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
 |
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 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
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 evaluation kits include a sample configuration file that sets up AMPS to work with the samples, and the AMPS Configuration Reference contains a full description of the configuration items with sample configuration snippets.
|
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. |
|
On older processor architectures, You can also set the
|
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-201X 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 For example, to set the variable
|
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.