Run the Satellite container using Docker

Follow this step-by-step guide on how to download, install, and run the Ingestion Satellite container using Docker on any operating systems.

Prerequisites

Docker Desktop is installed on your system.

• Docker Desktop for Linux (Ubuntu)

• Docker Desktop for macOS

• Docker Desktop for Windows

The recommended memory for one container is 4GB to 6GB.

Run the Satellite container

1. Pull the latest version of the Ingestion Satellite container.

docker pull levelops/ingestion-satellite

If you aren't able to execute the docker pull command, you can manually download the Ingestion Satellite image from Docker Hub and install it.

2. Run the Satellite container in the foreground. Replace `/absolute/path/to/satellite.yml` with the absolute path to your Satellite configuration file (`satellite.yml`)

docker run \
  -v /absolute/path/to/satellite.yml:/levelops/config.yml \
  levelops/ingestion-satellite

3. If everything is working as expected, you can run the Satellite container in the background by adding `-d --restart unless-stopped` to the `docker run` command. You can also optionally add `--name sei` to give the container a name if you are running multiple containers.

Option: Encrypt the `satellite.yml` Configuration

To avoid storing data at rest in the clear, you can encrypt satellite.yml. The Satellite can read AES-256 encrypted config files. You must provide an environment variable with the encryption password.

1. Use the following command to encrypt the configuration file. Edit the input path (/absolute/path/to/input/satellite.yml) and output path (/path/to/output/satellite.yml.enc) according to your environment.

docker run -i --rm -v /absolute/path/to/input/satellite.yml:/levelops/input \
  --entrypoint /bin/bash levelops/ingestion-satellite \
  -c 'java -cp /levelops/satellite-agent.jar -Dloader.main=io.levelops.ingestion.agent.Encrypt org.springframework.boot.loader.PropertiesLauncher input' \
  > /path/to/output/satellite.yml.enc

2. There is no prompt, but you must enter your password in the terminal, and then press enter. When entering your password, it appears in plain text, but it isn't stored.

3. Run the docker run command with an encryption password environment variable.

export ENCRYPTION_PASSWORD="<YOUR PASSWORD>"; docker run -d --restart unless-stopped \
  -v /absolute/path/to/satellite.yml.enc:/levelops/config.yml \
  --env ENCRYPTION_PASSWORD \
  levelops/ingestion-satellite

Decrypting the Configuration File (If Needed)

If you need to make changes later on, you can use the following command to decrypt the configuration file. As before you must edit the input path and output path according to your environment. You'll also need to enter your password and press enter.

docker run -i --rm -v /absolute/path/to/input/satellite.yml.enc:/levelops/input \
  --entrypoint /bin/bash levelops/ingestion-satellite \
  -c 'java -cp /levelops/satellite-agent.jar -Dloader.main=io.levelops.ingestion.agent.Decrypt org.springframework.boot.loader.PropertiesLauncher input' \
  > /path/to/output/satellite.yml

Troubleshooting: Satellite Can't Find `satellite.yml`

Errors mentioning ${levelops.api_key} indicate that the Satellite can't find the config file. This issue often occurs with older versions of Docker that may have problems when mounting single files. To resolve this issue, follow these steps:

1. Rename satellite.yml to config.yml.

2. Move the config.yml file into an empty folder.

3. On Linux, ensure that your user (not root) owns both the folder and the config.yml file, and that the permissions are not too restrictive (e.g., use chmod 755 if needed).

For newer versions of Docker, make sure that you are using the full paths and not relative paths.

For newer versions of Docker, it's essential to use full paths rather than relative paths when specifying file locations. Here's an example docker run command:

docker run \
  -v /absolute/path/to/parent/folder:/levelops/config \
  -e CONFIG_FILE=/levelops/config/config.yml \
  levelops/ingestion-satellite