Docker: Install and configure Microsatellites

Microsatellites aren’t supported for organizations hosted in the EU data center.

A public repository on Docker Hub offers the latest versions of the Microsatellite.

If you want to use a Helm chart to install Microsatellite to docker, follow these instructions.

You configure the Microsatellite using environment variables. Please see Microsatellite Configuration Parameters for a full listing and expanded explanations of variables and recommended settings. You can also use the following template and fill in your own values for the variables (defaults are entered for you, but you can change them).

If you want to use yaml instead of the command line, you can use the yaml file in the AWS configuration topic.

If you are happy with the default port numbers and don’t need TLS, you only need to modify the following:

satellite_key
pool

docker run
-e COLLECTOR_SPAN_FORWARDING_BUFFER_SIZE=20000
-e COLLECTOR_SATELLITE_KEY=<your-satellite-key>
-e COLLECTOR_POOL=<your-pool-nam>
-e COLLECTOR_GUID=<guid>
-e COLLECTOR_STATSD_HOST=
-e COLLECTOR_STATSD_PORT=
-e COLLECTOR_STATSD_EXPORT_STATSD=
#-----Only if using Datadog for Satellite Metrics----
-e COLLECTOR_STATSD_EXPORT_DOGSTATSD=
-e COLLECTOR_STATSD_DOGSTATSD_TAGS=
#-----------------------------------------------------
-e COLLECTOR_STATSD_PREFIX=lightstep
-e COLLECTOR_STATSD_SATELLITE_PREFIX=satellite
-e COLLECTOR_STATSD_CLIENT_PREFIX=client
-e COLLECTOR_PLAIN_PORT=8383 -p 8383:8383
-e COLLECTOR_SECURE_PORT=93939 -p 9393:9393
-e COLLECTOR_DIAGNOSTIC_PORT=8000 -p 8000:8000
-e COLLECTOR_ADMIN_PLAIN_PORT=8180 -p 8180:8180
-e COLLECTOR_ADMIN_SECURE_PORT= 8181 -p 8181:8181
-e COLLECTOR_TLS_CERT_PREFIX= ??
-e COLLECTOR_DISABLE_ACCESS_TOKEN_CHECKING=
-e COLLECTOR_PROJECT_NAME=
-e COLLECTOR_INGESTION_TAGS=
-e COLLECTOR_SAMPLE_ONE_IN_N=0

lightstep/microsatellite:latest

You can run the Microsatellite as a non-root user using a Cloud Observability-defined user without root permissions. Add the --user 999:999 flag to the docker run command. For example:
docker run --user 999:999

Here is an example using a Docker Compose file. This configuration sends spans over http on port 8182 with secure traffic configured to go over port 8183. Change the COLLECTOR_SATELLITE_KEY to your satellite key for your project, save it as docker-compose.yml and then do docker-compose up.

version: '3'
services:
  satellite:
    image: lightstep/microsatellite:latest
    environment:
      - COLLECTOR_SATELLITE_KEY=someLongRandomStringOfCharacters
      - COLLECTOR_PLAIN_PORT=8383
      - COLLECTOR_SECURE_PORT=9393
      - COLLECTOR_DIAGNOSTIC_PORT=8000
      - COLLECTOR_ADMIN_PLAIN_PORT=8180
    ports:
      - "8383:8383" #Span inegest, Required for unsecure traffic, or secure traffic that terminates it's secure status before it hits the satellite
      - "9393:9393" #Span ingest Required for secure traffic
      - "8000:8000" #Diagnostics
      - "8180:8180" #COLLECTOR_ADMIN_PLAIN_PORT, Required for health checks

After startup, check the diagnostics page (http://{satellite_host}:8000/diagnostics) to view the Microsatellite configuration. When starting from command line as in the above example, the configuration will also be directed to stdout, which you can inspect for troubleshooting if the diagnostics page isn’t reachable. Follow these instructions to further validate your installation and troubleshoot any issues.

You configure your instrumentation to communicate with your Microsatellite by providing their location. If you are using a single Microsatellite, you provide the DNS name or IP address of that Microsatellite. For more than one, use the name or address of the load balancer you’ve deployed. Find out how to do that in the language-specific Quickstart guides.

By default, client libraries use secure connections. If you’ve configured your Microsatellite to use plainport connections, you must configure your tracer appropriately.

Docker: Install and configure Microsatellites

See also