The following introduction will help you get up and running quickly with AMP.

We recommend installing the Docker CE stable channel release 17.09.1 on your system. Make sure you check the What to know before you install section on the Docker site for Mac OS and Windows to ensure your system meets the requirements.

• What to know before you install - Docker for Mac
• What to know before you install - Docker for Windows

NOTE: We currently do not support Docker Toolbox on any OS.

Mac OS

For the installers, go to Docker for Mac.

Configure Docker to use maximum CPU and at least half of the maximum memory. You can configure settings by right clicking the whale icon on the status bar and clicking Preferences -> Advanced. Make sure you apply these changes for Docker to be configured with the new settings.

Windows

For the installers, go to Docker for Windows.

Configure Docker to use maximum CPU and at least half of the maximum memory. You can configure settings by right clicking the whale icon in the Notifications area and clicking Settings -> Advanced. Make sure you apply these changes for Docker to be configured with the new settings.

Linux

You can find specific Linux distribution in the tables on Docker for Linux.

Download the latest release of the CLI for your platform from here. Place the amp binary from the release archive into some location in your system path.

For example:

$ sudo chmod +x ./amp
$ sudo mv ./amp /usr/local/bin

You can create an AMP cluster on your machine locally or on AWS.

Local cluster creation

This is the default mode for cluster creation on AMP.

Why do you need a local cluster?

During development of your application, you will want to have a quick and easy way of running and tearing down a cluster, rather than relying on a cloud based solution.

Prerequisites

Mac OS

To enable Docker engine metrics, you must add some configuration to the Docker daemon.

Right click on the whale icon, go to Preferences -> Daemon and select the Advanced tab, and add this:

{
    "experimental" : true,
    "metrics-addr" : "0.0.0.0:9323"
}

Make sure you apply these changes for Docker to be configured with the new settings.

Windows

To enable Docker engine metrics, you must add some configuration to the Docker daemon.

You can configure settings by right clicking the whale icon in the Notifications area and clicking Settings -> Daemon -> Advanced tab.

{
    "experimental" : true,
    "metrics-addr" : "0.0.0.0:9323"
}

Make sure you apply these changes for Docker to be configured with the new settings.

Linux

To enable Docker engine metrics, you must add some configuration to the Docker daemon.

Edit or create the daemon.json file in located etc/docker to include:

$ sudo nano /etc/docker/daemon.json
{
    "experimental" : true,
    "metrics-addr" : "0.0.0.0:9323"
}

You must perform this additional step to increase virtual memory needed for Elasticsearch.

$ sudo sysctl -w vm.max_map_count=262144

To make this change permanent, you can run the following and reboot:

$ echo "vm.max_map_count = 262144" | sudo tee -a /etc/sysctl.conf

Cluster Deployment

To create a cluster locally:

$ amp cluster create
...
2017/12/04 01:17:59 ampctl (version: 0.18.0-dev, build: a51daf88)
...
{"Swarm Status":"active","Core Services":17,"User Services":0}

This will create a single node swarm cluster on your machine and deploy AMP services on top of it.

Once you have started a local cluster, you will be able to deploy stacks and monitor the associated services by signing up.

$ amp user signup --name user1 --email user1@amp.com --password [password]
Verification is not necessary for this cluster.
Hi user1! You have been automatically logged in.

NOTE: See the user documentation in the AMP CLI Reference section for additional details about the user account related operations.

With the local cluster, you do not need to verify the account created and you will be logged in automatically after an account creation.

While deploying a local cluster, the default certificate is self-signed. You need to use the -k or --insecure option when using any of the AMP commands.

TIP: Set an alias for amp as alias amp='amp -k'.

What's next?

You can now deploy a stackfile on your newly created local cluster.

Cluster Status

You can check if a cluster is running or not by running the following command:

$ amp cluster status

The output of this command displays the provider, swarm status, and the number of core and user services running.

Provider:      local
Swarm Status:  active
Core Services: 17
User Services: 0

NOTE: You must be logged in to the AMP cluster to run this command.

Cluster Teardown

If you no longer use the deployed cluster, it can be removed by running the following command:

$ amp cluster rm

On success, the output looks something like this:

2017/12/08 21:49:40 ampctl (version: 0.18.0-dev, build: 4ad78fdd)
Removing service amp_agent
Removing service amp_alertmanager
Removing service amp_ampbeat
Removing service amp_amplifier
Removing service amp_cadvisor
Removing service amp_docker-engine
Removing service amp_elasticsearch
Removing service amp_etcd
Removing service amp_gateway
Removing service amp_grafana
Removing service amp_haproxy_exporter
Removing service amp_kibana
Removing service amp_nats
Removing service amp_nats_exporter
Removing service amp_nodes
Removing service amp_prometheus
Removing service amp_proxy
2017/12/08 21:49:40 waiting for all services to clear up...
2017/12/08 21:49:40 Removing container /amp_ampbeat.1.rwh3rnmwpf94rasrcah5hunk1 [Exited (1) 10 minutes ago]
2017/12/08 21:49:52 Removing container /amp_prometheus.1.bj1g2byp3te34sjov0rlz6gos [Exited (0) 9 seconds ago]
2017/12/08 21:49:52 Removing container /amp_nats_exporter.1.mv8lgp1c3jqm3ng009izh3oak [Exited (143) 9 seconds ago]
2017/12/08 21:49:55 Removing container /amp_agent.7z8aobvghzadvrb8n3zf22ake.pinz6oz4mk2m6y8h47455nrxk [Exited (137) 3 seconds ago]
2017/12/08 21:49:56 cleared up
2017/12/08 21:49:56 Removing volume [amp_etcd-data]...
2017/12/08 21:49:56 Removing volume [amp_ampagent]...
2017/12/08 21:49:56 Removing volume [amp_elasticsearch-data]...
2017/12/08 21:49:56 Removing volume [amp_prometheus-data]...
2017/12/08 21:49:56 Removing volume [amp_alertmanager-data]...
2017/12/08 21:49:56 Removing volume [amp_grafana-data]...
2017/12/08 21:49:56 Successfully removed network public [prn2d38x4q90vq3vqhejcb2h5]
2017/12/08 21:49:56 Successfully removed network monit [ik9ojg3hh5t2gdjv96s098cis]
2017/12/08 21:49:56 Successfully removed network core [zfc7cios4kmz4ogdknu5mrd2k]
2017/12/08 21:49:58 cluster deleted

TIP: Use -h or --help option for any of the AMP commands or sub-commands to more information about the command's usage.

AWS cluster creation

This page outlines the steps to set up an AMP cluster on AWS.

Why do you need an AMP cluster on AWS?

When you application is ready or when you want your team to share a common cluster, it is easy to spin up an AMP cluster on AWS.

Prerequisites

The prerequisites for creating an AWS cluster on AMP is to have:

AWS Account

You will need an AWS account with adequate IAM rights to deploy Cloud Formation stacks.

If you don't already have one, sign up here.

To learn more about managing IAM roles, see the official documentation from AWS here.

AWS Key Pair

You will need an AWS key pair specific to the region you choose.

For creating key pairs on AWS, see the official documentation from AWS here.

AWS Access Key

You will need to provide your AWS Access Key ID and AWS Secret Access Key in order to deploy an AMP cluster.

You can find out more about AWS access keys here.

NOTE: If you already have the AWS CLI installed on your system, make sure it is configured since the AMP CLI will use this information for cluster creation. See more details here.

Checklist

Before deploying your cluster, you will need the following elements:

• Pick a region, for instance us-west-2
• AWS Key pair name in the region you chose
• AWS Access Key ID
• AWS Secret Access Key
• Stack name

NOTE: If you already have the AWS CLI installed, the AMP CLI will use the Region, AWS Access Key ID and AWS Secret Access Key from it.

Cluster Deployment

If you don't have the AWS CLI installed, enter the following:

$ export REGION=us-west-2
$ export KEY_NAME=user-keypair
$ export ACCESS_KEY_ID=xxxxx
$ export SECRET_ACCESS_KEY=xxxxx
$ export STACK_NAME=amp-test

$ amp cluster create --provider aws --aws-region $REGION --aws-parameter KeyName=$KEY_NAME --aws-access-key-id $ACCESS_KEY_ID --aws-secret-access-key $SECRET_ACCESS_KEY --aws-stackname $STACK_NAME --aws-sync

If you have the AWS CLI installed, enter the following:

$ export KEY_NAME=user-keypair
$ export STACK_NAME=amp-test

$ amp cluster create --provider aws --aws-parameter KeyName=$KEY_NAME --aws-stackname $STACK_NAME --aws-sync

The AMP cluster deployment on AWS takes roughly 10 minutes to complete. On success, the output looks something like this:

Fri Dec  8 01:16:53 UTC 2017    amp-test                     CREATE_IN_PROGRESS (User Initiated)
Fri Dec  8 01:17:16 UTC 2017    Vpc                          CREATE_COMPLETE
Fri Dec  8 01:19:34 UTC 2017    ManagerAutoScalingGroup      CREATE_COMPLETE
Fri Dec  8 01:20:56 UTC 2017    ManagerWaitCondition         CREATE_COMPLETE
Fri Dec  8 01:21:02 UTC 2017    CoreWorkerAutoScalingGroup   CREATE_COMPLETE
Fri Dec  8 01:21:02 UTC 2017    UserWorkerAutoScalingGroup   CREATE_COMPLETE
Fri Dec  8 01:21:58 UTC 2017    CoreWaitCondition            CREATE_COMPLETE
Fri Dec  8 01:21:59 UTC 2017    UserWaitCondition            CREATE_COMPLETE
Fri Dec  8 01:23:50 UTC 2017    ApplicationWaitCondition     CREATE_COMPLETE
Fri Dec  8 01:23:54 UTC 2017    amp-test                     CREATE_COMPLETE
-------------------------------------------------------------------------------
VPC ID                                     | vpc-a92ec8d0
NFSv4 Endpoint                             | disabled
URL for cluster health dashboard           | amp-test-ManagerEx-8IKHVRJOUT98-636105687.us-west-2.elb.amazonaws.com:8080
internal endpoint for the registry service | disabled
public facing endpoint for the cluster     | amp-test-ManagerEx-8IKHVRJOUT98-636105687.us-west-2.elb.amazonaws.com

What's next?

You can now deploy a stackfile on your newly created local cluster.

Customization

The cluster has been created with the default configuration. You'll need to update it according to your convenience.

Domain Certificate

You should generate a certificate valid for the domain that will be served by the cluster. Ideally it can be a wildcard certificate, but it should at least include the virtual hosts amplifier, dashboard, kibana and alerts.

The default certificate is stored in the secret certificate_amp. It should include the private key, the certificate and the full certificate chain (in this order). Create a new secret with your new certificate:

$ cat certificate.pem | docker secret create certificate_amp_custom -

Update the services that use it:

$ docker service update --secret-rm certificate_amp --secret-add source=certificate_amp_custom,target=/run/secrets/cert0.pem amp_amplifier
$ docker service update --secret-rm certificate_amp --secret-add source=certificate_amp_custom,target=/run/secrets/cert0.pem amp_proxy

Check that the service is stabilizing with the new configuration

$ docker service ps amp_amplifier
$ docker service ps amp_proxy

Secrets

amp cluster create uses a docker secret named amplifier_yml for amplifier configuration.

If the secret is not present before the invocation of amp cluster create, it will be automatically generated with sensible values for the following keys:

• JWTSecretKey: A secret key of 128 random characters will be generated.
• SUPassword: A super user password of 32 characters will be generated and displayed during the execution of the command.

If the secret is already created, it will be used as is without any modifications.

Amplifier configuration

The secret amplifier_yml contains the configuration for the user registration. To enable it, you should get a Sendgrid key (you can have a 30 days trial key here.

$ cat > amplifier.yml << EOF
EmailKey: SENDGRID_KEY
SUPassword: SUPER_USER_PASSWORD
JWTSecretKey: JWT_RANDOM_STRING
EOF
$ cat amplifier.yml | docker secret create amplifier_yml_custom -

Update the service:

$ docker service update --secret-rm amplifier_yml --secret-add source=amplifier_yml_custom,target=/run/secrets/amplifier.yml amp_amplifier

Check that the service is stabilizing with the new configuration.

Alerting configuration

You can configure where notifications will be sent. The default (no notification configured) is in the secret alertmanager_yml.

Create a new file with your configuration:

$ cat > alertmanager.yml << EOF
---
global:
  slack_api_url: "https://hooks.slack.com/services/YOUR_WEB_HOOK"
templates:
- '/etc/alertmanager/template/*.tmpl'
route:
  receiver: 'slack-receiver'
  repeat_interval: 5m
  routes:
  - receiver: 'slack-receiver'
receivers:
- name: "slack-receiver"
  slack_configs:
  - channel: "@CHANNEL_NAME"
    username: "Alertmanager"
    title: '*DOMAIN_NAME* {{ range .Alerts }}{{ .Annotations.summary }} {{ end }}'
    text: '{{ range .Alerts }}{{ .Annotations.description }} {{ end }}'
    send_resolved: true
EOF
$ cat alertmanager.yml | docker secret create alertmanager_yml_custom -

Update the service:

$ docker service update --secret-rm alertmanager_yml --secret-add source=alertmanager_yml_custom,target=/run/secrets/alertmanager.yml amp_alertmanager

Check that the service is stabilizing with the new configuration.

Now you can also configure the alerts definitions. By default, the Docker config prometheus_alerts_rules contains empty rules.

Create a new file with the configuration. You can find an example in the amp repo in examples/monitoring/prometheus_alerts.rules.

$ cat prometheus_alerts.rules | docker config create prometheus_alerts_rules_custom -

Update the service

$ docker service update --config-rm prometheus_alerts_rules --config-add source=prometheus_alerts_rules_custom,target=/etc/prometheus/alerts.rules amp_prometheus

Check that the service is stabilizing with the new configuration.

Update the domain name

You should create or update the domain name that you use to create the certificate. Use a service such as route53, dnsimple or similar to create a CNAME pointing to the DNS name from the output of the cluster creation. If you don't have access to it anymore, you can find it in the output of the cloudformation stack on the AWS console.

Wait for the DNS to be updated.

Login and validate the configuration

Use the CLI from your workstation (not from the cluster anymore) and check that the connection is done and that the certificate is valid:

$ amp -s DOMAIN_NAME user ls

Then signup a new user

$ amp -s DOMAIN_NAME user signup --name LOGIN --email EMAIL

You should receive an email with a command line for the validation of the account.

Note that if it is a test cluster, you can skip certificate creation step and use -k (--insecure) AMP CLI argument.

Also you can grab public endpoint (ELB) DNS name from Cloudformation -> Stacks - Outputs -> DNSTarget key.

$ DOMAIN_NAME=nderzhak-ManagerE-1FQNBP6KF3O24-818587690.us-west-2.elb.amazonaws.com; ./amp -s $DOMAIN_NAME -k user ls
[nderzhak-ManagerE-1FQNBP6KF3O24-818587690.us-west-2.elb.amazonaws.com:50101]
USERNAME   EMAIL   CREATED ON
su                 29 Nov 17 14:41

Cluster Cleanup

You can remove the old secrets and config now that the cluster is configured and running.

$ docker secret rm amplifier_yml
$ docker secret rm alertmanager_yml
$ docker secret rm certificate_amp
$ docker config rm prometheus_alerts_rules

Cluster Teardown

If you no longer use the deployed cluster, it can be removed by running the following command:

$ amp cluster rm --provider aws --aws-stackname $STACK_NAME --aws-sync

The cluster teardown on AWS takes about 10 minutes to complete. On success, the output looks something like this:

Fri Dec  8 01:17:16 UTC 2017    Vpc                          CREATE_COMPLETE
Fri Dec  8 01:19:34 UTC 2017    ManagerAutoScalingGroup      CREATE_COMPLETE
Fri Dec  8 01:20:56 UTC 2017    ManagerWaitCondition         CREATE_COMPLETE
Fri Dec  8 01:21:02 UTC 2017    UserWorkerAutoScalingGroup   CREATE_COMPLETE
Fri Dec  8 01:21:02 UTC 2017    CoreWorkerAutoScalingGroup   CREATE_COMPLETE
Fri Dec  8 01:21:58 UTC 2017    CoreWaitCondition            CREATE_COMPLETE
Fri Dec  8 01:21:59 UTC 2017    UserWaitCondition            CREATE_COMPLETE
Fri Dec  8 01:23:50 UTC 2017    ApplicationWaitCondition     CREATE_COMPLETE
Fri Dec  8 01:23:54 UTC 2017    amp-test                     CREATE_COMPLETE
Fri Dec  8 01:26:12 UTC 2017    amp-test                     DELETE_IN_PROGRESS (User Initiated)
Fri Dec  8 01:26:14 UTC 2017    ApplicationWaitCondition     DELETE_IN_PROGRESS
Fri Dec  8 01:26:15 UTC 2017    UserWaitCondition            DELETE_IN_PROGRESS
Fri Dec  8 01:26:15 UTC 2017    CoreWaitCondition            DELETE_IN_PROGRESS
Fri Dec  8 01:26:17 UTC 2017    UserWorkerAutoScalingGroup   DELETE_IN_PROGRESS
Fri Dec  8 01:26:17 UTC 2017    CoreWorkerAutoScalingGroup   DELETE_IN_PROGRESS
Fri Dec  8 01:29:54 UTC 2017    ManagerWaitCondition         DELETE_IN_PROGRESS
Fri Dec  8 01:29:56 UTC 2017    ManagerAutoScalingGroup      DELETE_IN_PROGRESS
Fri Dec  8 01:35:11 UTC 2017    Vpc                          DELETE_IN_PROGRESS
Fri Dec  8 01:35:30 UTC 2017    amp-test                     DELETE_COMPLETE

You can deploy your own stacks on your AMP cluster. This section is a WIP.

Alternatively, if you wish to work with the latest development version directly from master on Github, you can fork the repo and build your own CLI. The entire toolchain has been containerized so you only need to install Docker.

TIP: Here is the official Go documentation explaining how to create a Go project structure and set GOPATH.

To get the repo setup, you can run the following set of commands to clone the repository into your go workspace and add the CLI path to your system PATH.

$ cd $GOPATH/src
$ mkdir -p github.com/appcelerator
$ cd github.com/appcelerator
$ git clone https://github.com/appcelerator/amp
$ cd amp
$ export PATH=$GOPATH/src/github.com/appcelerator/amp/bin/{YourOS}/amd64:$PATH

To build the CLI and the core AMP images, you can then run:

$ ampmake build

This will build cross-compiled versions of the CLI and place them in the appropriate locations under ./bin. In addition, this will build the development versions of each of the images necessary for creation of the AMP cluster.

The amp cluster command manages all cluster related operations for AMP.

Usage

$ amp cluster --help

Usage:  amp cluster [OPTIONS] COMMAND

Cluster management operations

Options:
  -h, --help                 Print usage
  -k, --insecure             Control whether amp verifies the server's certificate chain and host name
  -s, --server string        Specify server (host:port)
  -v, --volume stringSlice   Bind mount a volume

Management Commands:
  node        Cluster node management operations

Commands:
  create      Set up a cluster in swarm mode
  rm          Destroy an amp cluster
  status      Retrieve details about an amp cluster

Run 'amp cluster COMMAND --help' for more information on a command.

NOTE: Currently a number of amp cluster create options are in a state of transition. We recommend you stick to the outlined examples for deploying cluster environments.

For learning how to deploy a cluster locally on your machine, see the section on local cluster creation

For learning how to deploy a cluster on AWS, see the section on AWS cluster creation

TIP: Use -h or --help option for any of the AMP commands or sub-commands to more information about the command's usage.

Examples

Local cluster

• To create a cluster:

  $ amp cluster create

AMP comprises of 4 features:

• core (mandatory)
• metrics (optional)
• logs (optional)
• proxy (optional)

It is possible to disable the optional features using the following commands:

To create a local cluster without metrics:

$ amp cluster create --local-no-metrics

To create a local cluster without logging:

$ amp cluster create --local-no-logs

To create a local cluster without proxy:

$ amp cluster create --local-no-proxy

• To know the status of a cluster:

  $ amp cluster status

NOTE: You must be logged in to the AMP cluster to run this command.

• To remove a cluster:

  $ amp cluster rm

AWS cluster

• To create a cluster:

If you don't have the AWS CLI installed, enter the following:

$ export REGION=us-west-2
$ export KEY_NAME=user-keypair
$ export ACCESS_KEY_ID=xxxxx
$ export SECRET_ACCESS_KEY=xxxxx
$ export STACK_NAME=amp-test

$ amp cluster create --provider aws --aws-region $REGION --aws-parameter KeyName=$KEY_NAME --aws-access-key-id $ACCESS_KEY_ID --aws-secret-access-key $SECRET_ACCESS_KEY --aws-stackname $STACK_NAME --aws-sync

If you have the AWS CLI installed, enter the following:

$ export KEY_NAME=user-keypair
$ export STACK_NAME=amp-test

$ amp cluster create --provider aws --aws-parameter KeyName=$KEY_NAME --aws-stackname $STACK_NAME --aws-sync

• To remove a cluster:

  $ amp cluster rm --provider aws --aws-stackname $STACK_NAME --aws-sync

The amp completion command allows you to add shell completion to your AMP CLI.

Usage

$ amp completion --help

Usage:    amp completion SHELL [flags]

Output shell completion code for the specified shell (bash or zsh)

Examples:

        # Install bash completion on a Mac using homebrew

            $ brew install bash-completion

        Once installed, bash_completion must be evaluated.  This can be done by adding the
        following line to the .bash_profile, and reloading it

            source $(brew --prefix)/etc/bash_completion

            $ source $HOME/.bash_profile

        # Write bash completion code to a file

            $ amp completion bash > ~/.config/amp/completion.bash.inc

        Add this line in your $HOME/.bash_profile, and reload it

            source "$HOME/.config/amp/completion.bash.inc"

            $ source $HOME/.bash_profile

        # Load the amp completion code for zsh[1] into the current shell
        source <(amp completion zsh)

Options:
  -h, --help            Print usage
  -k, --insecure        Control whether amp verifies the server's certificate chain and host name
  -s, --server string   Specify server (host:port)

TIP: Use -h or --help option for any of the AMP commands or sub-commands to more information about the command's usage.

Installation

In order to use shell completion with AMP, follow the installation instructions for your corresponding shell.

Bash

Make sure bash completion is installed:

• Most current Linux OS (non-minimal installations) have bash completion.
• On Mac, install with brew install bash-completion

After bash completion is installed, add the following line to your ~/.bash_profile file:

source $(brew --prefix)/etc/bash_completion

Then, either source your ~/.bash_profile or launch a new terminal.

Now you need to write the bash completion, generated by AMP, to a file. We recommend writing it to a file in your $HOME/.config/amp directory.

$ amp completion bash > ~/.config/amp/completion.bash.inc

After doing this, add the following line to your ~/.bash_profile file to source your bash completion file.

source "$HOME/.config/amp/completion.bash.inc"

Then either source your ~/.bash_profile or launch a new terminal again.

Zsh

In a Zsh shell, load the amp completion code with:

$ source <(amp completion zsh)

or add source <(amp completion zsh) to your ~/.zshrc file.

Examples

With the shell completion code loaded for AMP, you can hit tab twice to view the shell completion.

$ amp
cluster     completion  config      login       logout      logs        password    service     stack       stats       team        user        version     whoami

$ amp stack
deploy    logs      ls        rm        services

$ amp stack deploy -c examples/stacks/pinger/
README.md   pinger.yml

The amp config command manages all configuration related operations for AMP.

Usage

$ amp config --help

Usage:    amp config [OPTIONS] COMMAND

Configuration management operations

Options:
  -h, --help            Print usage
  -k, --insecure        Control whether amp verifies the server's certificate chain and host name
  -s, --server string   Specify server (host:port)

Commands:
  create      Create a config from a file or STDIN as content
  ls          List configs
  remove      Remove one or more configs

Run 'amp config COMMAND --help' for more information on a command.

TIP: Use -h or --help option for any of the AMP commands or sub-commands to more information about the command's usage.

NOTE: To be able to perform any secret related operations, you must be logged in to AMP using a verified account.

Examples

• To create a config:

  $ amp config create test ./test
  66cxrj0wcn2ugqspyocmui2tb

  On success, this command returns an alphanumeric ID which is the secret ID.

• To list all config:

  $ amp config ls
  ID                          NAME
  66cxrj0wcn2ugqspyocmui2tb   test
  c74xny5z0nv5mtyb8cl8k799y   prometheus_alerts_rules

• To remove one or more configs:

  $ amp config rm test
  test

The amp logs command is used to query or stream logs. It provides useful filtering options to manage what is presented.

Usage

$ amp logs --help

Usage:    amp logs [OPTIONS] SERVICE [flags]

Display logs matching provided criteria

Options:
      --container string   Filter by the given Container
  -f, --follow             Follow log output
  -h, --help               Print usage
  -i, --include            Include AMP logs
  -k, --insecure           Control whether amp verifies the server's certificate chain and host name
  -m, --meta               Display entry metadata
      --msg string         Filter the message content by the given pattern
      --node string        Filter by the given node
  -n, --number int32       Number of results (default 1000)
  -r, --raw                Display raw logs (no prefix)
      --regexp             Treat '--msg' option as a regular expression
  -s, --server string      Specify server (host:port)
      --since int32        Number of days to include in the search (maximum 100) (default 2)
      --stack string       Filter by the given stack

TIP: Use -h or --help option for any of the AMP commands or sub-commands to more information about the command's usage.

NOTE: To be able to perform any logs related operations, you must be logged in to AMP using a verified account.

Examples

• To fetch and follow all the logs:

  $ amp logs -f

• To fetch and follow the logs for a specific service:

  $ amp logs -f amp_etcd

• To search for a specific pattern through all the logs:

  $ amp logs --msg error

• To fetch the logs for a service called foobar, using partial service name:

  $ amp logs foo

• To fetch infrastructure logs:

  $ amp logs -i

• To fetch all the logs and display metadata associated with each entry:

  $ amp logs -m

The amp password command is used to manage all password related operations for AMP.

Usage

$ amp password --help

Usage:    amp password [OPTIONS] COMMAND 

Password management operations

Options:
  -h, --help            Print usage
  -k, --insecure        Control whether amp verifies the server's certificate chain and host name
  -s, --server string   Specify server (host:port)

Commands:
  change      Change password
  reset       Reset password
  set         Set password

Run 'amp password COMMAND --help' for more information on a command.

TIP: Use -h or --help option for any of the AMP commands or sub-commands to more information about the command's usage.

Examples

• To update your current password:

  $ amp password change
  current password: [oldpassword]
  new password: [newpassword]
  Your password change has been successful.

• If you have forgotten your password and need it reset:

  $ amp password reset [username]

  NOTE: If you are working on a cluster without email verification, such as a local cluster, this command will be disabled.

An email with instructions to reset password will be sent to the registered email address. In this email, you will be sent a link to reset your password with or you can reset it with the provided CLI command.

• To set a new password:

  $ amp password set --token [token]

  NOTE: If you are working on a cluster without email verification, such as a local cluster, this command will be disabled

The amp secret command manages all operations related to AMP secrets.

Usage

$ amp secret --help

Usage:    amp secret [OPTIONS] COMMAND

Secret management operations

Options:
  -h, --help            Print usage
  -k, --insecure        Control whether amp verifies the server's certificate chain and host name
  -s, --server string   Specify server (host:port)

Commands:
  create      Create a secret from a file or STDIN as content
  ls          List secrets
  remove      Remove one or more secrets

Run 'amp secret COMMAND --help' for more information on a command.

TIP: Use -h or --help option for any of the AMP commands or sub-commands to more information about the command's usage.

NOTE: To be able to perform any secret related operations, you must be logged in to AMP using a verified account.

Examples

• To create a secret:

  $ amp secret create test ./test
  c60z5iv6kguxdk5p1n4p7lulm

  On success, this command returns an alphanumeric ID which is the secret ID.

• To list all secrets:

  $ amp secret ls
  ID                          NAME
  8lpnhb7k140s65ftdjwav1k35   certificate_amp
  c60z5iv6kguxdk5p1n4p7lulm   test
  huns47stt3ade3neufohl5pzg   alertmanager_yml
  i2gjv0m8ilhl5aqixmp0oeoy0   amplifier_yml

• To remove one or more secrets:

  $ amp secret rm test
  test

The amp service command is used to manage all service related operations for AMP.

Usage

$ amp service --help

Usage:    amp service [OPTIONS] COMMAND

Service management operations

Options:
  -h, --help            Print usage
  -k, --insecure        Control whether amp verifies the server's certificate chain and host name
  -s, --server string   Specify server (host:port)

Commands:
  inspect     Display detailed information of a service
  logs        Display logs of given service matching provided criteria
  ls          List services
  ps          List tasks of a service
  scale       Scale a replicated service

Run 'amp service COMMAND --help' for more information on a command.

TIP: Use -h or --help option for any of the AMP commands or sub-commands to more information about the command's usage.

NOTE: To be able to perform any service related operations, you must be logged in to AMP using a verified account.

Examples

• To inspect a service:

  $ amp service inspect pinger
  {
        "ID": "0k1fzgc2pfuyowej0gedm6kmr",
        "Version": {
                "Index": 231
        },
        "CreatedAt": "2017-07-05T22:00:41.444720874Z",
        "UpdatedAt": "2017-07-05T22:00:41.449032363Z",
        "Spec": {
                "Name": "pinger_pinger",
                "Labels": {
                        "com.docker.stack.namespace": "pinger"
                },
                "TaskTemplate": {
                        "ContainerSpec": {
                                "Image": "subfuzion/pinger:latest",
                                "Labels": {
                                        "com.docker.stack.namespace": "pinger"
                                },
                                "Env": [
                                        "SERVICE_PORTS=3000",
                                        "VIRTUAL_HOST=pinger.examples.*,https://pinger.examples.*"
                                ],
                                "StopGracePeriod": 10000000000,
                                "DNSConfig": {}
                        },
  ...

  TIP: Use the service-id or service-name as the argument.

• To list the available services with detailed status about their tasks:

  $ amp service ls
  ID                          NAME            MODE         REPLICAS   STATUS    IMAGE                 TAG
  0k1fzgc2pfuyowej0gedm6kmr   pinger_pinger   replicated   3/3        RUNNING   appcelerator/pinger      latest

  NOTE: this command only displays services which are part of user deployed stacks.

• To list the tasks of a service:

  $ amp service ps pinger_pinger
  ID                          NAME              IMAGE                        DESIRED STATE   CURRENT STATE   NODE ID                     ERROR
  2oyhxm5eon3u40didkvglc4oa   pinger_pinger.1   appcelerator/pinger:latest   RUNNING         RUNNING         7z8aobvghzadvrb8n3zf22ake
  9uy23btldzx9ww901djhaph4c   pinger_pinger.2   appcelerator/pinger:latest   RUNNING         RUNNING         7z8aobvghzadvrb8n3zf22ake
  nwm34nsxexmhujixni7b1k6gh   pinger_pinger.3   appcelerator/pinger:latest   RUNNING         RUNNING         7z8aobvghzadvrb8n3zf22ake

• To retrieve logs of a service:

  $ amp service logs pinger
         pinger_pinger.2 | listening on :3000
         pinger_pinger.1 | listening on :3000
         pinger_pinger.3 | listening on :3000
         pinger_pinger.2 | listening on :3000
         pinger_pinger.1 | listening on :3000
         pinger_pinger.3 | listening on :3000
  ...

  TIP: Use the service-id or service-name as the argument.

• To scale up or scale down the number of replicas of the service:

  $ amp service scale
  service id or name: pinger_pinger
  replicas: 2
  Service pinger_pinger has been scaled to 2 replicas.

The amp settings command displays settings for AMP CLI. It can be accessed by storing the value in a settings file or passing it as a command-line argument.

Usage

amp settings --help

Usage:    amp settings [flags]

Display AMP settings

Options:
  -h, --help            Print usage
  -k, --insecure        Control whether amp verifies the server's certificate chain and host name
  -s, --server string   Specify server (host:port)

In order to start using the CLI settings:

• You can either:
  • Create a new directory called .amp in the current working (local) directory and add the config file amp.yml in this directory, OR
  • Create a new directory called amp in the $HOME/.config directory and add the config file amp.yml in this directory (This is the default location).
• Add values to the file in format:
  • Variable: value

NOTE: For the moment, the settings file only stores the Server parameter, which is used to point the CLI to a target cluster. More will be added in future releases.

Examples

• If the settings file is placed in the directory $HOME/.config/amp with Server: local.appcelerator.io, you can view the settings of AMP using:

  $ amp settings
  [local.appcelerator.io:50101]
  Settings file: $HOME/.config/amp/amp.yml
  AMP Settings:
  Server:        local.appcelerator.io:50101

• If the settings file is placed in the directory $PWD/.amp with Server: local.appcelerator.io, you can view the settings of AMP using:

  $ amp settings
  [local.appcelerator.io:50101]
  Settings file: $PWD/.amp/amp.yml
  AMP Settings:
  Server:        local.appcelerator.io:50101

• If you have not defined a settings file:

  $ amp settings
  [127.0.0.1:50101]
  Settings file: none
  AMP Settings:
  Server:        127.0.0.1:50101

TIP: Use -h or --help option for any of the AMP commands or sub-commands to more information about the command's usage.

The amp stack command is used to manage all stack related operations for AMP.

Usage

$ amp stack --help

Usage:    amp stack [OPTIONS] COMMAND 

Stack management operations

Options:
  -h, --help            Print usage
  -k, --insecure        Control whether amp verifies the server's certificate chain and host name
  -s, --server string   Specify server (host:port)

Commands:
  deploy      Deploy a stack with a Docker Compose v3 file
  logs        Display filtered logs for stack
  ls          List deployed stacks
  rm          Remove one or more deployed stacks
  services    List services of a stack

Run 'amp stack COMMAND --help' for more information on a command.

TIP: Use -h or --help option for any of the AMP commands or sub-commands to more information about the command's usage.

NOTE: To be able to perform any stack related operations, you must be logged in to AMP using a verified account.

Examples

• To deploy a stack using a compose file:

  $ amp stack deploy -c examples/stacks/counter/counter.yml counter
  Deploying stack counter using examples/stacks/counter/counter.yml
  Creating service counter_go
  Creating service counter_redis

  NOTE: If no name is specified for the stack, the name of the stack will be the filename.

• To list the deployed stacks, with detailed status about their services:

  $ amp stack ls
  ID                                                                 NAME      RUNNING   COMPLETE   PREPARING   TOTAL   SERVICES   STATUS    OWNER
  95508f3ca3ad3877e8c33e69a92a9e3490eb60395bd1b26f0c6f80f1f5521976   counter   2         0          0           2       2/2        RUNNING   su

  NOTE: this command only displays stacks created by the user. No infrastructure stacks are displayed.

• To list the services within a stack:

  $ amp stack services counter
  ID            NAME           MODE        REPLICAS  IMAGE
  k5fzzzryjpda  counter_redis  replicated  1/1       redis
  njsru7ka1gek  counter_go     replicated  3/3       htilford/go-redis-counter

• To view the logs of the entire stack:

  $ amp stack logs counter
  ...
  1:M 05 Jul 21:21:36.050 # WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128.
  1:M 05 Jul 21:21:36.056 # Server started, Redis version 3.2.9
  1:M 05 Jul 21:21:36.056 # WARNING you have Transparent Huge Pages (THP) support enabled in your kernel. This will create latency and memory usage issues with Redis. To fix this issue run the command 'echo never > /sys/kernel/mm/transparent_hugepage/enabled' as root, and add it to your /etc/rc.local in order to retain the setting after a reboot. Redis must be restarted after THP is disabled.
  ...

• To update a stack with a new compose file:

  $ amp stack deploy -c examples/stacks/counter/counter-2.yml counter
  Deploying stack counter using examples/stacks/counter/counter-2.yml
  Updating service counter_go (id: njsru7ka1gek1xzdt6z4b8wez)
  Updating service counter_redis (id: k5fzzzryjpdaanlvqqu5b5qr7)

• To remove a stack:

  $ amp stack rm counter
  Removing service counter_redis
  Removing service counter_go

The amp team command is used to manage all team related operations for AMP.

Usage

$ amp team --help

Usage:    amp team [OPTIONS] COMMAND

Team management operations

Options:
  -h, --help            Print usage
  -k, --insecure        Control whether amp verifies the server's certificate chain and host name
  -s, --server string   Specify server (host:port)

Management Commands:
  member      Manage team members
  resource    Manage team resources

Commands:
  create      Create team
  get         Get team information
  ls          List teams
  rm          Remove one or more teams

Run 'amp team COMMAND --help' for more information on a command.

TIP: Use -h or --help option for any of the AMP commands or sub-commands to more information about the command's usage.

NOTE: To be able to perform any team related operations, you must be logged in to AMP using a verified account.

Examples

NOTE: amp team commands that require the --team option will remember the last used team using a local preferences file. If you want to override this, specify the --team option in the command.

• To create a team:

  $ amp team create team
  Team has been created.

• To retrieve details of a specific team:

  $ amp team get team
  Team: team
  Created On: 05 Dec 17 15:25

• To retrieve the list of teams:

  $ amp team ls
  TEAM   CREATED ON
  team   05 Dec 17 15:25

• To remove a team:

  $ amp team rm team
  team

Team Member Management Commands

The amp team member command is used to manage all team member related operations for AMP.

Usage

$ amp team member --help

Usage:    amp team member [OPTIONS] COMMAND

Manage team members

Options:
  -h, --help            Print usage
  -k, --insecure        Control whether amp verifies the server's certificate chain and host name
  -s, --server string   Specify server (host:port)

Commands:
  add         Add one or more members
  ls          List members
  rm          Remove one or more members

Run 'amp team member COMMAND --help' for more information on a command.

Examples

• To add a member to a team:

  $ amp team member add johndoe
  team name: team
  Member(s) have been added to team.

  NOTE: The member to be added to the team must be a existing and verified user account.

• To list members in a team:

  $ amp team member ls --team team
  team name: team
  MEMBER
  sample
  johndoe
  ...

• To remove a member from a team:

  $ amp team member rm johndoe
  team name: team
  johndoe

Team Resource Management Commands

The amp team resource command is used to manage all team resource related operations for AMP.

Usage

$ amp team resource --help

Usage:    amp team resource [OPTIONS] COMMAND

Manage team resources

Options:
  -h, --help            Print usage
  -k, --insecure        Control whether amp verifies the server's certificate chain and host name
  -s, --server string   Specify server (host:port)

Commands:
  add         Add one or more resources
  ls          List resources
  perm        Change permission level over a resource
  rm          Remove one or more resources

Run 'amp team resource COMMAND --help' for more information on a command.

Examples

• To add a resource to a team:

  $ amp team resource add 93fce7d3f...
  team name: team
  Resource(s) have been added to team.

  NOTE: Resources can be stacks.

• To list resources available to a team:

  $ amp team resource ls
  team name: team
  RESOURCE ID                                                        PERMISSION LEVEL
  93fce7d3fc8ada786c7db6956849343bcc5700f65d8b1512523561166a2ec455   TEAM_READ

• To change the permission level of a resource:

  $ amp team resource perm 93fce7d3f... write
  team name: team
  Permission level has been changed.

  The default permission level of a resource is read. The permission level can be changed to read, write or admin.

• To remove a resource from a team:

  $ amp team resource rm --team team 93fce7d3f...
  team name: team
  93fce7d3fc8ada786c7db6956849343bcc5700f65d8b1512523561166a2ec455

The amp user command is used to manage all user related operations for AMP.

Other user-related commands that are not managed by amp user include login, logout and whoami.

Usage

$ amp user --help

Usage:    amp user [OPTIONS] COMMAND

User management operations

Options:
  -h, --help            Print usage
  -k, --insecure        Control whether amp verifies the server's certificate chain and host name
  -s, --server string   Specify server (host:port)

Commands:
  forgot-login              Retrieve account name
  get                       Get user information
  ls                        List users
  resend-verification-token Resend verification email to registered address
  rm                        Remove one or more users
  signup                    Signup for a new account
  verify                    Verify account

Run 'amp user COMMAND --help' for more information on a command.

TIP: Use -h or --help option for any of the AMP commands or sub-commands to more information about the command's usage.

Examples

NOTE: For the purpose of illustration, we will use the local cluster (which is default) for running AMP commands.

• To signup for a new user account:

  $ amp user signup
  [your.server.com:50101]
  username: sample
  email: sample@amp.com
  password: [password]
  [user sample @ your.server.com:50101]
  Hi sample! Please check your email to complete the signup process.

  NOTE: If you are working on a cluster without email verification, such as a local cluster, you will not need to verify your account as you will not be sent an email and you will be logged in automatically.

   amp user signup
   [127.0.0.1:50101]
   username: sample
   email: sample@amp.co,
   password:
   Verification is not necessary for this cluster.
   Hi sample! You have been automatically logged in.

After signing up, you will then be sent an email to your registered address. In this email, you will be sent a link to verify your account with or you can verify your account with the provided CLI command.

• To verify your account using the token in verification email:

  $ amp user verify [token]
  [your.server.com:50101]
  Your account has now been activated.

  NOTE: If you are working on a cluster without email verification, such as a local cluster, this command will be disabled.

   amp -k user verify <TOKEN>
   [user sample @ 127.0.0.1:50101]
   Error: `amp user verify` disabled. This cluster has no registration policy

  If you are using hosted AMP, you will need to verify your account.

• To login to your new account:

  $ amp login
  [127.0.0.1:50501]
  username: sample
  password: [password]
  Welcome back sample!

• Once you have logged in, you can check who is currently logged in with amp whoami:

  $ amp whoami
  [user sample @ 127.0.0.1:50101]
  Logged in as user: sample

  In addition, every amp command will display who you are logged in as at the top of the command output.

  $ amp
  [user sample @ 127.0.0.1:50101]
  
  Usage:  amp [OPTIONS] COMMAND
  ...

• To logout of your account:

  $ amp logout
  [user sample @ 127.0.0.1:50101]
  You have been logged out!

• In the instance that you have forgotten the username associated with your email, you can have the username sent to your registered email account:

  $ amp user forgot-login sample@amp.com
  Your login name has been sent to the address: sample@amp.com

  NOTE: If you are working on a cluster without email verification, this command will be disabled.

• To retrieve details of a specific user:

  $ amp user get foo

• To retrieve a list of users:

  $ amp user ls

• To remove a user:

  $ amp user rm foo

  This command only allows you to delete your own account. If you try to delete another user, you will see the following error:

  $ amp user rm sample1
                      [user sample @ 127.0.0.1:50101]
                              Error: user not authorized

  However, the `su` account has the privileges of removing other accounts in the cluster.

The amp version command displays the current version of AMP.

Usage

$ amp version --help

Usage:    amp version [flags]

Show version information

Options:
  -h, --help            Print usage
  -k, --insecure        Control whether amp verifies the server's certificate chain and host name
  -s, --server string   Specify server (host:port)

Examples

TIP: It would be useful to set an alias for amp as alias amp='amp -k' in case the certificate on the server is not valid.

NOTE: For the purpose of illustration, we will use the local cluster (which is default) for running AMP commands.

• To view the client and server version for AMP:

  $ amp version
  Client:
   Version:       v0.10.0-dev
   Build:         6f590348
   Server:        127.0.0.1:50101
   Go version:    go1.8
   OS/Arch:       darwin/amd64
  Server:
   Version:       v0.10.0-dev
   Build:         04daab98
   Go version:    go1.8.1
   OS/Arch:       linux/amd64

  NOTE: The above example is just a sample of the output of amp version command. The output will vary according to the version of AMP used.

• Viewing the version when the target server doesn't exist:

  $ amp version
  Client:
   Version:       v0.12.0-dev
   Build:         4166f646
   Server:        127.0.0.1:50101
   Go version:    go1.8
   OS/Arch:       darwin/amd64
  Server:         not connected
   Error:         unable to establish grpc connection: context deadline exceeded

  NOTE: The above example is just a sample of the output of amp version command. The output will vary according to the version of AMP used.