2. Crank Up the AMPS¶

This chapter is for users who are new to AMPS and want to quickly get a simple instance of AMPS running. This chapter will describe how to install AMPS on a Linux system, describe the layout of the AMPS distribution, and use the included spark command line AMPS client to send and receive a simple message. If you are on a Windows system without easy access to a Linux installation, a section at the end of the chapter includes information on configuring a Linux virtual machine.

Installing AMPS¶

On the 60East website at http://www.crankuptheamps.com/evaluate the current release of AMPS is available for evaluation download.

To get started, download the Linux installation to a directory on your Linux system.

Installing AMPS is simply a matter of unpacking the distribution. The distribution contains the complete set of libraries and dependencies needed to run the AMPS server on a typical Linux server distribution. No additional software or packages are necessary for the server itself.

To install AMPS, unpack the distribution in the directory 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 are the following sub-directories:

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

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/develop 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. The full set of options is described in the AMPS Configuration Reference.

The AMPS server generates a minimal sample configuration file with the --sample-config option. 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 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.

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 and would typically persist monitoring statistics to a file. Such a configuration 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.

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 sample 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.

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

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)

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:

*ampServer 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 command line 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`

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 AMPS commands from the command line. spark is a Java application, and requires Java runtime environment version 1.7 or later on the system.

spark is most commonly used for ad hoc testing or simple maintenance tasks. For more complicated tasks or more sophisticated maintenance, 60East recommends using one of the client libraries (such as the AMPS Python Client).

To test spark with the sample configuration, run the following command:

$ $AMPSDIR/bin/spark ping -server localhost:9007 -type json

This command tests connectivity to the AMPS server running at port 9007 on the local system. It confirms that the server is listening on that port using the default protocol for AMPS and accepts JSON messages on that port. The command should produce output like the following:

Successfully connected to tcp://username@localhost:9007/amps/json

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

Tip

It’s important to keep in mind that spark only provides basic functionality – that is, operations that don’t require any particular application logic or special handling. This guide uses spark for examples where possible, but some features of AMPS (for example, setting certain headers on messages published to AMPS) are only available through the AMPS client libraries.

JSON Messages - A Quick Primer¶

AMPS includes support for a wide variety of message types, as well as the ability to develop custom message types and to send binary payloads. This section focuses on JSON as the main message type used for samples in this guide. We use JSON for the guide because the format is simple, easily readable, and already in use in many environments.

JSON format is a simple, standardized message format. JSON has two basic constructs:

Objects that consist of key / value pairs
Arrays of values

JSON supports hierarchical construction: the value for a key can be a single value, an array of values, or another set of key/value pairs. For example, the following JSON message includes two nested sets of key value pairs. Notice that a key only needs to be unique within each set of values – the name value for the ship does not conflict with the name value for the character.

{
    "id" : 73,
    "character" : {
        "name" : "Han Solo",
        "occupation" : "smuggler",
        "ship" : {
            "name"  : "Millennium Falcon",
            "speed" : ".5 past light speed",
            "cargo" : [ "widgets", "baskets", "spice"]
        }
    }
}

Many AMPS applications use JSON as the payload. In addition, the amps protocol used to send commands to AMPS represents commands in a simplified subset of JSON. For example, a publish command might look like:

{"c":"publish","t":"test-topic"}{ "id" : 1, "message" : "Hello, World!" }

The command to AMPS, using the amps protocol, can be treated as a JSON document which contains the header information for AMPS – in this case, a publish to the topic test-topic. The header is followed by the message body, the payload of the command.

While the amps protocol is implemented as a subset of JSON, you can use any message type with the amps protocol: the header for the command will still be JSON, while the body can be in the message type of your choice, as in the sample below, which publishes to an XML topic:

{ "c":"publish","t":"xml-topic"}<example><id>1</id><message>Hello, world!</message></example>

The AMPS client libraries create and parse AMPS headers. For example, the publish method in the AMPS client libraries creates the appropriate header for a publish command based on the provided parameters.

Your applications use the Message and Command interfaces of the AMPS client libraries to work with the AMPS headers. There is no need for your application to parse or serialize the AMPS headers directly.

Tip

The AMPS client libraries handle creating and parsing AMPS headers. They do not parse or interpret the payload data on a received Message, instead the payload is returned as a sequence of bytes (or as a string).

Evaluating AMPS on Windows or MacOS¶

The AMPS server runs on 64-bit Linux operating systems. If you do not have access to a Linux system or a recent version of Windows, 60East recommends creating a Linux virtual machine to host the instance of AMPS. This is a convenient option for development systems, and allows you to easily experiment with different AMPS configurations on a dedicated system.

This section provides general information for creating a virtual machine image for use as a local development or evaluation environment.

This section assumes that you are familiar with Linux and the virtualization program you will be working with. It focuses on information specific to AMPS.

Using Windows Subsystem for Linux 2¶

If your development system is running a recent version of Windows, then Windows Subsystem for Linux 2 is a good option for developing with AMPS. Getting AMPS running is simply a matter of starting a Linux shell, downloading AMPS, and following the directions for Linux.

Notice that Windows Subsystem for Linux 2 does not provide access to some of the functionality that the AMPS server expects: in particular, the AMPS NUMA subsystem may not be able to determine the physical processor layout, and may report warnings on startup. Nevertheless, this can be a very good option for doing AMPS evaluation and development on a Windows system.

Creating a Virtual Machine Image¶

When creating the virtual machine image, 60East recommends the following parameters:

x64 processor
At least 4GB of memory allocated to the virtual machine
Minimum of 120GB drive space (most will be consumed by the operating system image)
At least 2 virtual processors

AMPS itself can run with less memory, processor, and disk capacity than recommended here. However, these settings will typically provide reasonable performance and enough capacity to do basic development work.

Virtual Box Settings¶

When installing AMPS on Virtual Box, 60East strongly recommends setting the network hardware emulation to use the Paravirtualized network adapter (virtio-net). For recent versions of Linux, performance is dramatically improved (even over the loopback interface) when using this setting.

Choosing a Linux Distribution¶

AMPS runs well on any Linux distribution that meets the basic requirements. The Ubuntu Linux distribution is a good choice, and is frequently used by both customers and the 60East developers as a development workstation environment. Visit https://www.ubuntu.com/download to download the latest released version of Ubuntu.

Whichever distribution you choose, 60East recommends that you download the .iso file and use that file to install the operating system.

Installing the Linux Distribution¶

AMPS itself doesn’t require anything beyond a basic operating system distribution. For the best experience while you are evaluating and getting to know AMPS, 60East recommends that you choose a profile optimized for software development or desktop use.

Select the following additional packages if your distribution does not already install them:

Python 2.6/2.7 or 3. The utility scripts in the AMPS distribution require Python.
Java runtime environment (1.7 or more recent). The spark command line AMPS client is written in Java, and requires a JRE. This guide assumes that you have a JRE available, and presents examples using spark.
g++, gdb, and your IDE of choice if you will be developing C++ applications with AMPS.
A web browser such as Firefox or Google Chrome

Filesystem Considerations¶

AMPS is designed and tested to use a Linux-based filesystem such as ext4 or filesystems that provide full native Linux filesystem semantics (for example, using nfs mounted filesystems for testing or archival purposes).

Mounting another type of filesystem (for example, an NTFS volume) in a VM, container, or WSL 2 may cause failures or unexpected results, since that approach may not provide all of the filesystem operations that AMPS uses.

When using a container, VM, or WSL2, make sure that AMPS and the files that AMPS creates are hosted on filesystems that support Linux file operations, in particular, that a process running under the Linux environment can memory map files hosted on that filesystem.

Next Steps¶

Once you have created the virtual machine image and installed your Linux distribution of choice, you can install and start AMPS as described in Installation.

Table Of Contents

Related Topics