Compose (docker-compose) and Docker (docker) CLI

This page outlines commonly used docker-compose and docker commands used in GroundWork Monitor.

Tips

  • Important! Mistakes can be made when typing Docker commands. You may want to consider a system backup.
  • For additional reference see Compose command-line reference and Docker commands. You can also see this information by running docker-compose [SUBCOMMAND] --help from the command line
  • Note docker-compose service names are the short names for the containers as listed in gw8/docker-compose.yml. , e.g., revproxy, cloudhub, groundwork, nagios. The .yml file should not be edited.
  • You will need to be in your GroundWork Monitor 8 installation directory (e.g., /path-to/gw8) before executing commands.
  • To create a shortcut for use when entering docker-compose commands you can create an alias. This enables you to use dc <command> versus the full docker-compose <command>. Just add an alias in the /home/gwos directory and bashrc file. For example:
    • Edit bashrc:
      vi .bashrc
    • At the bottom of the file add: 
      alias dc=docker-compose
    • Save the file and try it out, with the dc command alone you should receive a list of docker compose commands:
      :wq
      exit
      sudo su - gwos
      dc

Containers

CommandDescription
List Containers

docker ps

List running containers
Lists all running containers in Docker, not only GroundWork containers.

docker ps -a

List all containers
Includes containers not running.

docker-compose ps

List running GroundWork containers
Shows status of containers. Uses full container names, these are services in the current docker-compose.yml deployment.

Start Stop Restart Containers
docker-compose up -d

Start GroundWork containers
Starts containers in the background and leaves them running, add the -d for detached mode background output.

docker-compose down

Stop GroundWork containers
Removes containers, networks, volumes, and images created by docker-compose up.

docker-compose down
docker-compose up -d
docker-compose ps

Restart GroundWork containers
Within the gw8 directory, stop GroundWork containers, start GroundWork containers, list running GroundWork containers.

Start Stop Restart Individual Containers

docker-compose start <service>

Start individual container (service) 
(docker-compose nagios)

docker-compose stop <service>

Stop individual container (service)
Used as a proper shutdown.
(docker-compose stop nagios)

docker-compose restart <service>

Restart individual service
Stop and start service.
(docker-compose restart nagios)

docker-compose kill <service>

Force stop a container (service)
Use when docker-compose stop <service> is not working.
(docker-compose kill nagios)

Execute Commands

docker-compose exec

Execute a command running in a container
Example 1:
You can run bash as in:
docker-compose exec -u 1000 nagios bash
This logs into the nagios container and runs a shell in the container OS. 
Example 2:
You can run psql (the postgres client in the container) as in:
docker-compose exec -u 1000 pg psql
(-u 1000 option puts you in the container named as the container's default user)

Logs

Command SyntaxDescription

docker-compose logs --tail=<#> <service>

docker-compose logs -f --tail=<#> <service>

Display (and follow) a log file for a container

Examples:
Display log file:
docker-compose logs --tail=125 groundwork (125 line output for groundwork container)
docker-compose logs --tail=50 cloudhub (50 line log output for groundwork container)
docker-compose logs --tail=100 nagios (125 line log output for nagios container)

Display and follow log file (just add -f to above):
docker-compose logs -f --tail=125 groundwork
docker-compose logs -f --tail=50 cloudhub
docker-compose logs -f --tail=100 nagios

Output to text file:
docker-compose logs > gw8.txt (output all container logs to a text file)
docker-compose logs cloudhub > gw8_cloudhub.txt (output cloudhub container log to a text file)

docker-compose exec <service> </src/docker_cmd.sh enableAccessLogging>

docker-compose exec <service> </src/docker_cmd.sh disableAccessLogging>

Enable/disable logging

By default, access logging is disabled on all containers. However, there are Docker commands to enable them temporarily for diagnostic reasons. As logging is more expensive with the ELK Stack integrated, access to logs should not be left on during normal operation. Containers log independently, so any combination of the containers below can be enabled/disabled. Normally, revproxy access logging is sufficient to debug client/server communications.

Examples:
# main rail, (revproxy)
docker-compose exec revproxy /src/docker_cmd.sh enableAccessLogging
docker-compose exec revproxy /src/docker_cmd.sh disableAccessLogging

# monarch
docker-compose exec monarch /src/docker_cmd.sh enableAccessLogging
docker-compose exec monarch /src/docker_cmd.sh disableAccessLogging

# rstools
docker-compose exec rstools /src/docker_cmd.sh enableAccessLogging
docker-compose exec rstools /src/docker_cmd.sh disableAccessLogging

Check Docker Access

CommandDescription

docker

Verify access to Docker

docker-compose

Verify access to Docker Compose

Volumes

CommandDescription

docker volume ls

List all volumes

Versions

CommandDescription

docker -v

Show Docker version

docker-compose -v

Show Compose version

Cloud Hub Connections

CommandDescription

docker-compose exec cloudhub bash -c

This command will give you a line of output for each deployed connector instance, and will also show you the display name so you can disambiguate multiple deployments of the same connector type.

Example:
docker-compose exec cloudhub bash -c 'grep -r displayName /usr/local/groundwork/config/cloudhub/*'

Advanced Mode

Configuring the Details

In many cases, no additional configuration beyond what is possible in the user interface will be needed. There are, however, some areas of the system that support customizations and tuning. If you are an advanced user, you will need to access these to get the most out of your system. To use these customizations and make tuning changes, you will need to edit some of the files the system uses to control the applications, settings, and parameters.

NeDi Example

For example, we ship the NeDi application with no access to the database snapshot interface. If you want to use it, you must change the following line (un-comment) in the file /usr/local/groundwork/config/nedi/nedi.conf:

from:

#module System Database db adm

to:

module System Database db adm

The file should then be saved, and the permissions should be left at -rw-rw-r-- 1 nedi nedi. That is, owned by the nedi user.

Such changes are preserved across upgrades.

Additions of files and deletions of files are NOT preserved, but will be reverted on upgrades. This ensures we can provide you with a secure, functional system with minimal instability.

While we are working on adding more ways to configure GroundWork Monitor to the user interface, we expect for the foreseeable future some aspects will require command line editing of configuration files, and possibly the restarting of containers. The following instructions are provided to enable you to make these changes safely and without having to master too many new commands.

Generally speaking, you will want to have your GroundWork Monitor 8 system running, and use a docker feature called docker exec to make changes in the containers. Don't try to go around the containers and access the files directly on the file system. The containers are there for your protection, and will help you to be efficient in your editing.

So, to make the change described above, enter:

cd gw8
docker-compose exec -u 1000 nedi bash
CODE

This will place you at a shell in the container as the nedi user, for example:

nedi@3d83bf92a6d2:/src#

Change to the mounted configuration volume directory for nedi:

cd /usr/local/groundwork/config/nedi
CODE

Edit the file with vi:

vi nedi.conf
CODE

Make the change(s) and save the file. It is then good practice to check that it is still at the native permissions:

ls -la nedi.conf
CODE

You should see something like this:

-rw-rw-r-- 1 nedi nedi 21706 Dec 3 21:32 /usr/local/groundwork/config/nedi/nedi.conf

Leave the shell:

exit
CODE

NeDi makes immediate use of the changes you make to its settings file. There's no need to restart the container in this case. You are done!

Using similar procedures, you can access the nagios container, for example:

docker-compose exec -u 1000 nagios bash

Using the -u 1000 option puts you in the container as the container's default user (nedi, nagios, etc.). If you leave it out, you will get a root shell, which is not recommended, since you can easily make a change that will leave your container (and perhaps the entire monitoring system) inoperable.

Container Directories

The directories you can access will vary by container.

For the Nagios container, the directories:

/usr/local/nagios/etc
/usr/local/nagios/libexec

are useful for testing, and custom settings, though we caution against adding custom plugins to your system. They will vanish on upgrade!

A better way is to use GDMA (see the GDMA Monitoring documentation).

The global settings can be configured by making changes to the files in /usr/local/groundwork/config.

Configuration files available:

  • application-users.properties
  • check_cacti.conf
  • cloudhub-log4j.xml
  • cloudhub-logback.xml
  • cloudhub.properties
  • db.properties
  • event-feeder.conf
  • foundation-log4j.xml
  • foundation.properties
  • groundwork.lic
  • influxdb.properties
  • install.properties
  • ldap.properties
  • log-archive-receive.conf
  • log-archive-send.conf
  • menu.json
  • perfdata.properties
  • register_agent_by_discovery.conf
  • register_agent.properties
  • statistics-feeder.conf
  • status-feeder.properties
  • ws_client.properties
  • cloudhub-docker-3.xml

In addition, there are subdirectories that contain more files and templates that you can manage:

  • /certs
  • /cloudhub
  • /migrations
  • /nedi
  • /profiles
  • /rstools
  • /vema

The thing to remember is that changing these settings files can affect multiple aspects of the system. Make sure you comment your changes so they are easily reversible, and make regular backups of the system so you can revert the whole thing if you make a catastrophic change.

Related Resources