Link with Docker

The mablhq/link-agent Docker image includes everything the Link Agent needs, including its own Java runtime, so you don't install anything else on the host. This article explains which image to use and how to run the Link Agent in a Docker container.

Step 1: Choose an image

The image comes in two variants:

mabl recommends the latest tag, which always points at the newest release of the Link Agent. Each release is also tagged with its version, such as 3.0.1, and each tag has -alpine and -ubuntu forms, such as 3.0.1-ubuntu. The plain tags are the Alpine variant. Pin a version tag only if you need to control exactly when the image changes.

Pull the image on the machine where you will run the Link Agent:

docker pull mablhq/link-agent:latest

Step 2: Run the Link Agent

Running the Link Agent requires the following arguments:

• {your-api-key}: your "Link Agent" API key
• {tunnel-name}: the tunnel name, between 1 and 24 characters long, using lowercase letters, numbers, and dashes

To try the Link Agent in the foreground:

docker run --rm mablhq/link-agent:latest --api-key {your-api-key} --name {tunnel-name}

To keep it running in the background and restart it with the Docker daemon:

docker run -d --name mabl-link-agent --restart unless-stopped --stop-timeout 90 \
  mablhq/link-agent:latest --api-key {your-api-key} --name {tunnel-name}

--stop-timeout 90 gives the Link Agent time to let in-flight connections finish when you stop the container. Docker's default of 10 seconds can cut off tests that are running through the tunnel.

Use a configuration file

A Link Agent configuration file keeps your API key off the command line and lets one container serve several tunnels. Mount the directory that holds the file into the container, and point the agent at it:

docker run -d --name mabl-link-agent --restart unless-stopped --stop-timeout 90 \
  -v /etc/mabl-link:/config:ro \
  mablhq/link-agent:latest --config /config/config.yaml

Mount the directory rather than the file itself. The Link Agent watches the file and applies your edits while it runs, and many editors save a file by replacing it, which a single-file mount doesn't pick up.

Support for HTTP forward proxies

If your network requires it, you can configure the Link Agent to use an HTTP forward proxy, including support for basic proxy authentication. The Link Agent also supports proxy auto-configuration (PAC) through a configuration file.

Reaching services on the Docker host

Inside a container, localhost refers to the container itself, not the Docker host. To test a service that listens on the host's localhost, run the container with host networking (--net=host). See Testing localhost with mabl Link.

Tuning the host

mabl recommends raising the Docker host's socket-buffer limits, which increases tunnel throughput over long network paths. A container can't change these settings for itself, so apply them on the Docker host. See Raise the host's socket-buffer limits.

Step 3: Confirm the Link Agent is connected

After starting the Link Agent, go to Settings > Networking in the mabl app. The Link Agent appears in the Agents table and should show Connected within a minute or two. See Link Agent setup.

To see the Link Agent's output, run docker logs -f mabl-link-agent.

Update the Link Agent

Like other installations, the Link Agent in a container checks for a new version each time the container starts. An update it installs that way stays in that container only, and a container you recreate starts again from its image. To move to the newest image, pull it again and recreate the container:

docker pull mablhq/link-agent:latest
docker stop mabl-link-agent
docker rm mabl-link-agent
docker run -d --name mabl-link-agent --restart unless-stopped --stop-timeout 90 \
  mablhq/link-agent:latest --api-key {your-api-key} --name {tunnel-name}

Use the same options you started the container with, such as the configuration file mount.

docker stop lets in-flight connections finish, up to the container's stop timeout. If the tunnel has other agents, you can also put this one into maintenance mode first and wait for it to show Drained, so that new tests go to the other agents while it drains.

Next steps

Once the Link Agent is installed and running, configure your tests to run over mabl Link.