Quick Start

Congratulations! You have followed the install guide and now have a working lcp-compose command.

lcp-compose is a 100% command line tool that is mostly configuration driven. By-default, lcp-compose attempts to read it's configuration from .lcp-compose/config.yml from the current working directory.

The path .lcp-compose/ is dedicated for lcp-compose to store it's configuration file, and other generated files such as the docker-compose file and service specific configurations.

Developers can optionally check-in this directory to their version control systems to maintain a consistent lcp-compose configuration within their teams.

Initialization

If this is the first time we are using lcp-compose on a project, the tool must initialize it's configuration with sane defaults.

$ lcp-compose init --with-splunk

After the command completes, you can open the configuration directory, default .lcp-compose/ and examine the generated configuration files.

.lcp-compose/
|-- configurations/     # Service configuration (generated)
|-- config.yml          # lcp-compose configuration file. 
`-- docker-compose.yml  # docker-compose file (generated)

lcp-compose Services

The lcp-compose initializes itself to use the latest image for each service from dev-docker.points.com.

To see the current configuration, what services are configured, and the docker images they are using, issue the following command.

$ lcp-compose services
Working directory    :  .lcp-compose
Logging directory    :  /Users/raj.perera/dev/lcp-compose/.lcp-compose/logs
Config directory     :  /Users/raj.perera/dev/lcp-compose/.lcp-compose/configurations
Docker-compose file  :  /Users/raj.perera/dev/lcp-compose/.lcp-compose/docker-compose.yml
Service          Type       URL                      Docker Image                      Is Managed?
---------------  ---------  -----------------------  --------------------------        -------------
platform_core    core       http://platform_core/    image: pts/platform-core:latest   Yes
celery           core       N/A                      image: pts/celery:latest          Yes
sandbox_gateway  core       http://sandbox.gateway/  - UNMANAGED -                     No
security         core       http://security/         image: pts/security:latest        Yes
gateway          core       http://gateway/          image: pts/gateway:latest         Yes
buy              pluggable  N/A                      - UNMANAGED -                     No
orders           pluggable  N/A                      - UNMANAGED -                     No
Note: `build:` paths are displayed relative to working directory.

Service Types

Flags are used to identify the services defined within lcp-compose.

Managed Service

A service that has it's life-cycle controlled by lcp-compose. These services must be configured with a docker image URI or a path to a valid Dockerfile.

Managed services can be configured by using the lcp-compose manage command:

# Configure security service to use a local Dockerfile path
→ lcp-compose manage security --build-path=../security

# Configure gateway to use a different docker image 
→ lcp-compose manage gateway --image-id=dev-docker.points.com/gateway:SPECIFIC_VERSION

Unmanaged Service

A service that lcp-compose will not manage, but assume to exist. Useful when a service must be replaced by an external endpoint, but specifics such as URLs are needed to template configuration for other managed services.

Any lcp-compose service can be replaced by an external endpoint (ie: local development server, remote server, etc.) by using lcp-compose unmanage command:

# Configure the local LCP stack to use orders service on FT environment.
→ lcp-compose unmanage orders --url=http://orders-ft.lxc.points.com:1200/

# Configure orders service as an unmanaged service listening on the host machine 
→ lcp-compose unmanage orders --local-service-on-port=5000

ProTip: Any service type, including infrastructure, can be toggled between managed and unmanaged states.

Search for Service Images

lcp-compose has the ability to search a Docker registry for images. This is particularly useful if you want to pin the version of a dependency to a known-good image.

e.g., if you want to pin the platform-core image to a specific released image, you can search for it using:

lcp-compose search rc-docker.points.com/platform-core

rc-docker.points.com/platform-core:release-2016-45-2
rc-docker.points.com/platform-core:release-2016-45-3
rc-docker.points.com/platform-core:release-2016-45-4
[ ... ]
rc-docker.points.com/platform-core:release-2017-09
rc-docker.points.com/platform-core:release-2017-13
rc-docker.points.com/platform-core:release-2017-14-1

The output is ordered by alphabetically, except for the case when tags are numerical, then the tags will be ordered numerically. e.g.,:

lcp-compose search dev-docker.points.com/buy

[ ... ]
dev-docker.points.com/buy:1106
dev-docker.points.com/buy:1108
dev-docker.points.com/buy:1111
dev-docker.points.com/buy:1114
dev-docker.points.com/buy:1115
dev-docker.points.com/buy:1116
dev-docker.points.com/buy:1123
dev-docker.points.com/buy:1124
dev-docker.points.com/buy:1125
dev-docker.points.com/buy:1126
dev-docker.points.com/buy:1131
dev-docker.points.com/buy:1132
dev-docker.points.com/buy:1133
dev-docker.points.com/buy:1135
dev-docker.points.com/buy:1140
dev-docker.points.com/buy:1141
dev-docker.points.com/buy:1142
dev-docker.points.com/buy:latest

When used on a registry that requires authentication (e.g., the on-prem Gitlab registry), you will be prompted for username/password when needed.

For gitlab, the password is your Gitlab API access token. Create one here.

You're also able to supply username/password through command line flags: --username=YOUR_AD_USERNAME, --password=YOUR_GITLAB_ACCESS_TOKEN.

nb: If you're not authorized to a certain registry, you will get 401 Unauthorized error. Do not attempt to retry before being granted access since Gitlab authorization is tied to Active Directory, you're risking your account being locked down if you have too many failed attempts in a short period of time.

Deployment

After you have the performed required configuration, you can spin up the LCP stack by:

lcp-compose up

To check if all services are up, use docker ps or lcp-compose ps.

You can also run the sanity tests as part of the deployment:

lcp-compose up --verify

Note: It is expected that services will bootstrap themselves (create databases, ES indexes, etc.) at container entrypoint.

Interacting with Services

lcp-compose will configure your system's DNS settings to resolve service names to the appropriate container IPs. To access the service, simply curl the services name.

$ curl gateway/_health
{
  "health": "red",
  "services": {
    "buy": "red",
    "configuration": "red",
    "core": "green",
    "fraud-checks": "red",
    "gift": "red",
    "jreports": "red",
    "moves": "red",
    "offers": "red",
    "orders": "red",
    "reports": "red",
    "security": "green",
    "transfer": "red"
  }
}

Logs

You can tail the logs by using: lcp-compose logs [service_name].

If Splunk is set up as a managed service, simply point your browser to the URL http://splunk:8000/ to get to the Splunk interface.

Shutting down

Simply issue the command lcp-compose down to stop and remove all running containers owned by the current configuration.

Extras

View Service Dependencies

lcp-compose provides a convenient way to help you visualize component dependencies. To do that, use lcp-compose graph command. This command generates the service dependency graph in dot format and can be viewed by GraphViz.

To install graphiz on Ubuntu:

apt-get install graphviz

To generate the graph in pdf format:

lcp-compose graph | dot -Tpdf -o output.pdf

Then you can use your favourite PDF viewer to open the file.

Alternatively, you can copy the DOT code generated by lcp-compose graph and paste it to http://mdaines.github.io/viz.js/ where you can get the graph in your browser.