Running an Application

Applications can be launched using either Predix Edge Manager or Predix Edge Technician Console (PETC). These programs interact with Predix Edge Agent, which launches the application to the local Docker Stack system running on the Predix Edge device. Predix Edge Agent launches applications using Docker Stack. A docker-compose.yml file defines the number and behavior of containers in the application. It is recommended developers test their docker-compose files to confirm they execute as expected using Docker Stack running locally on a development machine (either Mac or the Predix Dev VM).

To start an application in a Dev environment using Docker Stack:

docker stack deploy -c docker-compose-local.yml my-app-name

To stop an application:

docker stack rm my-app-name

When you test locally, your local docker-compose.yml file should include volume mounts for /config and /data. The docker-compose.yml file that is ultimately deployed to Predix Edge can either comment these out, or remove them altogether. It is recommended to have two docker-compose.yml files as follows:

docker-compose.yml – Predix Edge requires this spelling when uploading an application tar.
docker-compose-local.yml – Use this file when running locally for testing.

Deploying to PETC

Note that the application will launch after the Deploy step. You may need to stop the application and Apply the config, then start the application.

Running applications is a three-step process.

Upload the application.
Deploy the application.
Apply the configuration.

Deploying to Edge Manager

Note that applications will launch after the Deploy step. You may need to stop the application and Apply the config, then start the application.

Upload the application and config to the repository.
Deploy the application to a group of devices.
Apply the configuration.

Troubleshooting

While there are numerous problems that can occur with running multi-container applications, most are easily solvable. The following tips may be helpful when building and running Predix Edge applications.

Local:

Run Locally – In the initial stages of development most problems are with the new code you write. Run locally and check the log files using the docker logs or docker service logs commands.
Check Running Status – When running locally ‘docker stack ps <app-name>’ shows the status of each container. ‘docker stack ps <app-name> --no-trunc’ may also provide additional useful information.
Check Log Files – ‘docker ps’ followed by ‘docker logs <id-here>’.
Env Vars – Check that the docker-compose-local.yml has the required environment variables edefined.
Volume Mounts - Check that the docker-compose-local.yml has the /config, /data or /edge-agent volume mounts.
Docker Network – Check that the network is set up like the examples provided, with predix-edge-broker_net.
Proxy – Ensure the environment variables are set and that the container knows about them. Add this to the docker-compose-local.yml.
Note: This differs when running in Predix Edge OS.
```
http_proxy: ${http_proxy}
https_proxy: ${https_proxy}
HTTP_PROXY: ${HTTP_PROXY}
HTTPS_PROXY: ${HTTP_PROXY}
no_proxy: ${no_proxy} 
```

Common to all deployments:

Flopping Container – The Docker Stack keeps stopping and restarting a new instance of the container. Usually this is because the source code is unable to start. Check or try the following:
- Dockerfile – the Dockerfile might be referencing an invalid folder.
- Configs in /config – Ensure the code can find the configs in the /config volume mount.
- Data in /data – Ensure the volatile code is writing to /data. It is possible that it is writing to a different read-only file system folder, which might cause unexpected behavior the second or third time it is launched.
Have a look around. Execute these commands to use ssh to get inside the container. Look for permissions problems, launching the app problems, access to /config and /data.
- docker ps
- docker exec -it <id-of-container> /bin/sh
Launch the app yourself – update the docker-compose.yml with an entrypoint override, then execute the commands above to get inside the container and launch the app manually.
- entrypoint: ["sh", "-c", "sleep 500000"]

PETC and Edge Manager:

Check Running Status – In the UI visit the Applications/Application page. Check the status for each container, it should be Running.
Apply Configs – A common mistake is to Deploy the app but not the Configs. Most container logic will fail if missing its configuration.
Env Vars – Check that docker-compose.yml, bundled with the app tar, has the env vars needed.
Volume mounts – Upload will fail if docker-compose.yml has volume mounts.
Docker Network – Check that the network is set up like the examples provided, with predix-edge-broker_net.
Hostname vs. IP – In docker-compose.yml give your container a Hostname since the IP will vary when running in an Edge OS VM or physical instance.
Proxy – Ensure the container is aware of proxy environment variables. In PETC this is set on each device, usually before enrollment.
- Add the following to a service that has logic looking for proxy env vars (e.g., HTTPS_PROXY). PETC puts them in /etc/environment and docker-compose.yml needs to have an entry that loads it.
  - env_file: -/etc/environment
- b. Some code does not reference env vars for proxy info, ensure the config is set up.

PETC:

Check logs. In the UI:

Navigate to the Applications page.
Choose Service Name.
Choose Additional Options.
Set Message Priority to Debug.
The log viewer only shows the first 20 rows in the date range, so you might need to narrow the range.
Confirm the time range is accurate.
Click the Update Preview button.
Download the logs locally to view more details.

Edge Manager:

Upload the logs using a command:

Navigate to Device Manager > Devices.
Select the device.
Select Commands.
Click the Execute Command button.
Select Get Journal Log. Click Next.
Fill out the form. Click Execute.
Wait up to 30 seconds for the command to execute.
Click the Download link to view the file.