Skip to main content

Satellite via Docker

Prerequisites​

Before installing the Levo Satellite via Docker, ensure you have:

  • Docker Engine version 18.03.0 or higher
  • Admin privileges on the Docker host
  • 'docker-compose' installed, if 'docker compose' is not supported on your OS
  • At least 4 CPUs
  • At least 8 GB RAM

1. Download Shell Script File​

Download the Levo Satellite installation script to your server using one of the following commands:

wget https://docs.levo.ai/artifacts/satellite/levo_satellite.sh

2. Install Satellite​

a. Set executable permissions​

Ensure the script has executable permissions by running:

chmod +x ./levo_satellite.sh

b. Configure environment variables​

Set the following environment variables with your Levo credentials:

export LEVOAI_AUTH_KEY='Authorization Key'
export LEVOAI_ORG_ID='Org ID'
info

You may need to set a different Levo base URL if your SaaS/dashboard account is in the India region.

For example, if you are accessing Levo dashboard with app.india-1.levo.ai, also set:

export LEVOAI_BASE_URL='https://api.india-1.levo.ai'

start and upgrade then fetch docker-compose.yml from the matching regional docs site. Set LEVOAI_DOCS_URL to override this, for example an internal mirror.

Alternative: save the configuration to a file

Instead of exporting these variables in every shell, you can run the interactive setup once:

./levo_satellite.sh init

This prompts for your Authorization Key, Organization ID and Base URL, and writes them to a .levoenv file alongside the script. The Satellite reads that file on every start, restart and upgrade, so the configuration persists across new shell sessions and sudo.

c. Start Levo Satellite​

Execute the following command to start the Levo Satellite:

./levo_satellite.sh start
note

If you are running the script with sudo, ensure that the environment variables are also set with sudo. Otherwise, the script will not have access to these variables.

Alternatively, you can use the -E flag with sudo to preserve the user-defined environment variables:

sudo -E ./levo_satellite.sh start

This ensures the script can access the required environment variables without explicitly redefining them under sudo.

3. Verify connectivity with Levo.ai​

a. Check Satellite health​

The Satellite is comprised of the following components:

ComponentRole
levoai-haproxyGateway. Listens on port 80 and routes incoming Sensor traffic to the right component. This is the only port a Sensor talks to.
levoai-collectorReceives API traces from the Sensors.
levoai-satelliteServes Sensor configuration and receives eBPF/HAR traffic.
levoai-taggerProcesses traffic, detects PII and builds API schemas.
levoai-ionHandles on-prem data sync with Levo SaaS.
levoai-rabbitmqInternal message queue between components.

Wait a couple of minutes after the installation, and check the health of the components by executing:

docker ps -f name=levoai

All components should show Up and (healthy):

CONTAINER ID   IMAGE                               COMMAND                  CREATED         STATUS                   PORTS                                                        NAMES
b82fc90aef82   levoai/haproxy:latest               "docker-entrypoint.s…"   2 minutes ago   Up 2 minutes (healthy)   0.0.0.0:80->8080/tcp                                         levoai-haproxy
2b32cd6b9ced   levoai/collector:stable             "/usr/local/bin/levo…"   2 minutes ago   Up 2 minutes (healthy)   0.0.0.0:4317->4317/tcp, 127.0.0.1:8888->8888/tcp             levoai-collector
06f3c597cad0   levoai/satellite:stable             "gunicorn --capture-…"   2 minutes ago   Up 2 minutes (healthy)   0.0.0.0:9999->9999/tcp                                       levoai-satellite
89026034c567   levoai/satellite:stable             "python -OO /opt/lev…"   2 minutes ago   Up 2 minutes (healthy)                                                                levoai-tagger
5f1c0a934e21   levoai/satellite:stable             "python -OO /opt/lev…"   2 minutes ago   Up 2 minutes (healthy)                                                                levoai-ion
f74524d02fbd   rabbitmq:3.13.7-management-alpine   "docker-entrypoint.s…"   2 minutes ago   Up 2 minutes (healthy)   0.0.0.0:5671-5672->5671-5672/tcp, 0.0.0.0:15672->15672/tcp   levoai-rabbitmq

b. Check connectivity​

Execute the following to check for connectivity health:

docker logs levoai-tagger | grep "Ready to process; waiting for messages."

If connectivity is healthy, you will see output similar to the following:

{"level": "info", "time": "2022-06-07 08:07:22,439", "line": "rabbitmq_client.py:155", "version": "fc628b50354bf94e544eef46751d44945a2c55bc", "module": "/opt/levoai/e7s/src/python/levoai_e7s/satellite/rabbitmq_client.py", "message": "Ready to process; waiting for messages."}

4. Note the Host and Port Information​

Sensors connect to the Satellite through HAProxy (levoai-haproxy), which listens on port 80 on all of the host's network interfaces. HAProxy is the Satellite's gateway — it routes each request to the correct internal component, so port 80 is the only port a Sensor needs.

Please note down either the host's IP address or domain name. The Sensor will be configured to communicate with the Satellite at <Host's IP|Domain-Name>:80.

Make port 80 reachable from your Sensors

Sensors normally run on other hosts, so allow inbound TCP traffic on port 80 to the Satellite host from wherever your Sensors run — host firewall (firewalld/ufw), cloud security groups (AWS/Azure/GCP) and any network ACLs in between.

Verify from a Sensor host:

curl -sS -o /dev/null -w "%{http_code}\n" http://<Satellite-Host>/healthz

A 200 response means the gateway is reachable. If this times out, Sensors cannot deliver traffic even though the Satellite looks healthy on its own host.

Please proceed to install traffic capture sensors.

Satellite Lifecycle Management​

Stop the Levo Satellite​

Execute the following command to stop or uninstall Levo satellite components:

./levo_satellite.sh stop

Restart the Levo Satellite​

To restart the Levo satellite components, execute:

./levo_satellite.sh restart

Upgrade the Levo Satellite​

Execute the following command to upgrade the existing Satellite setup.

This command will download the latest Docker Compose file and restart all Satellite components:

./levo_satellite.sh upgrade

Share Satellite logs with support@levo.ai​

Execute the following command to collect logs from all Satellite components. This will create an archive at /tmp/docker_compose_logs_%date-time%.tar.gz:

./levo_satellite.sh get-logs

Configuration​

Change the Minimum Number of URLs for API Endpoint Detection​

To detect an API endpoint, the Satellite waits for at least 10 URLs to match that endpoint's URL pattern. This threshold may cause delays in detecting API endpoints when there is insufficient load.

To adjust this threshold:

  • Navigate to the Levo dashboard
  • Click Settings in the left navigation bar
  • Under the API Discovery tab, update Min. URLs per Pattern to your desired number
  • Wait at least 5 minutes for the Satellite to apply the change

Troubleshooting​

Tagger Errors​

The Tagger component sends API endpoint metadata to Levo.ai. API Observability will not function if the Tagger is in an errored state.

Please see sample output below from docker ps | grep -E "levoai/collector|levoai/satellite|bitnami/rabbitmq", that shows the Tagger (2nd line item) in an errored state:

65fe40867c70   levoai/collector:stable   "/usr/local/bin/levo…"   5 minutes ago   Up 5 minutes                    0.0.0.0:4317->4317/tcp, 9411/tcp                                                                                                         levoai-collector
45d6c4cccb28   levoai/satellite:stable   "python -OO /opt/lev…"   5 minutes ago   Restarting (1) 55 seconds ago                                                                                                                                            levoai-tagger
721b5431369a   levoai/satellite:stable   "gunicorn --capture-…"   5 minutes ago   Up 5 minutes                    0.0.0.0:9999->9999/tcp                                                                                                                   levoai-satellite
a00dc710d4af   bitnami/rabbitmq:3.10     "/opt/bitnami/script…"   5 minutes ago   Up 5 minutes                    5551-5552/tcp, 0.0.0.0:4369->4369/tcp, 5671/tcp, 0.0.0.0:5672->5672/tcp, 0.0.0.0:15672->15672/tcp, 0.0.0.0:25672->25672/tcp, 15671/tcp   levoai-rabbitmq

Below are common error scenarios:

Authentication Errors​

The Tagger component authenticates with Levo.ai using the Authorization Key. If Tagger is unable to authenticate, it will error out.

Check for authentication errors in the Tagger logs:

docker logs levoai-tagger | grep "Exception: Failed to refresh access token"

If there are exception messages, you have an incorrect or stale Authorization Key. Please contact support@levo.ai for further assistance.

Connectivity Errors​

Check for connectivity errors in the Tagger logs:

docker logs levoai-tagger | grep "ConnectionRefusedError: [Errno 111] Connection refused"

If there are exception messages, the Tagger is unable to connect to dependent services. It typically establishes connection after 3-4 retries.

Enable Debug Logging​

Set the following environment variable to enable debug logging for the Satellite components, then reinstall the Satellite or restart the containers:

export LEVOAI_LOG_LEVEL='DEBUG'

This will enable detailed debugging logs for all satellite components, including Tagger, Collector, Ion, and Satellite.

Some various log levels that can be set are INFO, DEBUG, WARNING, ERROR. The default log level is INFO.

Need Help?​

For further assistance, please reach out to support@levo.ai.

Was this page helpful?