Skip to main content

Run the Satellite container

Use Ingestion Satellites to integrate with on-premise tools and set up Custom integrations.


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

  1. Download and install Docker Desktop.


On Linux, add your user to the Docker group so that you can run Docker commands without root or sudo.

sudo usermod -aG docker $(whoami)

You need to log out and log back in for the change to take effect.

  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.

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

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 \

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 can happen with older versions of Docker that can experience issues when mounting single files. To resolve this issue:

  1. Rename satellite.yml to config.yml, and then move the file into an empty folder.

  2. On Linux, check that your user (not root) owns both the folder and file, and that permissions are not too restrictive (as with chmod 755).

  3. Run the docker run command with the parent folder instead of the specific config file.

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

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 \
  1. If everything is working, run the container in the background by adding -d --restart unless-stopped.

    docker run -d --restart unless-stopped \
    -v /absolute/path/to/satellite.yml:/levelops/config.yml \
  2. Optionally, add --name sei to give the container a name. Use a unique name per container if you are running more than one.

Manage background containers

These commands are helpful for managing background containers.

# list containers
docker container ls

# stop or restart container with ID
docker container stop <ID>
docker container restart <ID>

# delete container by ID
docker rm <ID>

In addition to Ingestion Satellites and other integrations, you can import CSV files and display the data in Table reports.