Documentation

Using Outrig with Docker

This guide covers how to use Outrig when your Go application runs inside Docker containers (as of Outrig v0.9.0)

Prerequisites

Before using Outrig with Docker, you must first install and run the Outrig monitor on your host machine (not inside the container). The Outrig server needs to be running locally to collect data from your containerized applications.

→ Follow the Quick Start guide to install and run Outrig on your host machine first.

Overview

When running Go applications in Docker containers, the Outrig SDK automatically detects the Docker environment and attempts to connect to host.docker.internal:5005 to communicate with the Outrig server on your host machine. In most Docker setups, no additional configuration is needed.

Note

Note for Linux Users: Docker on Linux doesn't automatically resolve host.docker.internal. The recommended solution is to use Docker's built-in host-gateway feature:

Run with host-gateway (recommended):

docker run --add-host=host.docker.internal:host-gateway <your-image>

Or map the Outrig port explicitly:

docker run -p 5005:5005 <your-image>

Container Integration

To use Outrig with your containerized Go application, you need to:

Install the Outrig binary inside your Docker container
Run your application using outrig run instead of go run

Step 1: Install Outrig in Container

Add the Outrig installation to your Dockerfile. For Alpine-based images:

# ---- START: Outrig Integration (Alpine) ----
RUN apk add --no-cache curl
RUN curl -sf https://outrig.run/install.sh | sh
RUN ln -sf ~/.local/bin/outrig /usr/local/bin/outrig
# ---- END: Outrig Integration ----

Note

For Debian/Ubuntu or CentOS/RHEL images, you can typically omit the apk add line, as curl is usually pre-installed.

To pin Outrig to a specific version (recommended for production), specify it like this:

# ---- START: Outrig Integration ----
RUN apk add --no-cache curl
RUN curl -sf https://outrig.run/install.sh | OUTRIG_VERSION=0.9.1 sh
RUN ln -sf ~/.local/bin/outrig /usr/local/bin/outrig
# ---- END: Outrig Integration ----

You can also download the Outrig .tar.gz, .deb, or .rpm files from our Github Releases Page and install them manually in your Dockerfile if you prefer not to use the install script.

Step 2: Run Your Application with Outrig

Instead of using go run main.go, use outrig run main.go to build and run your application with Outrig integration:

# Run your application using outrig run
RUN outrig run main.go

The outrig run command accepts most go run build flags, so you can pass through options like -ldflags:

RUN outrig run -ldflags "-X main.BuildTime=$(date +%Y%m%d%H%M%S)" main.go

Note

You may also use the SDK directly in your code, but the outrig binary must still be installed for log capture.

Complete Example

Here's a complete Dockerfile example for a Go application with Outrig:

FROM golang:1.24-alpine

# ---- START: Outrig Integration ----
RUN apk add --no-cache curl
RUN curl -sf https://outrig.run/install.sh | sh
RUN ln -sf ~/.local/bin/outrig /usr/local/bin/outrig
# ---- END: Outrig Integration ----

WORKDIR /app

# Cache dependencies for quick rebuilds
COPY go.mod go.sum ./
RUN go mod download

# Copy and run your Go application
# Can use most `go run` build flags (e.g. -ldflags)
#   as they will be passed directly through to go run.
COPY . .
RUN outrig run -ldflags "-X main.OutrigBuildTime=$(date +%Y%m%d%H%M%S)" main.go

# Set the entrypoint to run your application
EXPOSE 8080
CMD ["./main"]

That's it! Your containerized Go application will automatically connect to the Outrig server running on your host machine.