Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

sauce-connect: improve docker installation docs and document api-address changing in docker #2858

Merged
merged 3 commits into from
Jul 24, 2024
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
sauce-connect(install): update docker installation docs
mmatczuk committed Jul 24, 2024
commit 9a32bb772be7a9d5341f999cae2b7050267db0e4
223 changes: 178 additions & 45 deletions docs/secure-connections/sauce-connect-5/installation/docker.md
Original file line number Diff line number Diff line change
@@ -4,70 +4,203 @@ title: Run Sauce Connect in Docker
sidebar_label: Docker
---

Sauce Connect Proxy release includes [Docker](https://www.docker.com/) image to support a containerized CI/CD environment, see [Sauce Connect Docker container](https://github.com/saucelabs/sauce-connect-docker) for more information.
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Here are some benefits/use cases for using containerized Sauce Connect Proxy:
Sauce Connect Proxy container images are available on [Docker Hub](https://hub.docker.com/r/saucelabs/sauce-connect).

- You want to run Sauce Connect Proxy as part of a containerized CI/CD.
- You want to utilize a rich ecosystem of tools and services that container orchestration tools, such as Kubernetes, provide.
## Pull image

## What You’ll Need
The easiest way to get started with Sauce Connect Proxy in Docker is to pull the latest version of the image from Docker Hub.

- A Sauce Labs account ([Log in](https://accounts.saucelabs.com/am/XUI/#login/) or sign up for a [free trial license](https://saucelabs.com/sign-up)).
- A [Docker Hub](https://hub.docker.com/r/saucelabs/sauce-connect) account
- A [Docker Engine Installed and configured](https://docs.docker.com/engine/install/)
```bash
docker pull saucelabs/sauce-connect
```

## Running the Sauce Connect Docker Container
You can also specify a specific version by using a tag.

1. Pull the Sauce Connect Proxy Docker Image from the [Docker Hub](https://hub.docker.com/r/saucelabs/sauce-connect).
- To pull the latest version of Sauce Connect Proxy (recommended):
```bash
$ docker pull saucelabs/sauce-connect:5.1
```
- To use a specific version, add it as a tag:
```bash
$ docker pull saucelabs/sauce-connect:5.1.1-amd64
```
<details>
<summary>Supported tags</summary>
- 5, 5.1, 5.1.1<br/>
</details>
2. To run the Sauce Connect Proxy Docker image, modify and run the script below.
```bash
docker pull saucelabs/sauce-connect:<tag>
```

```bash
$ SAUCE_USERNAME="my-user" SAUCE_ACCESS_KEY="my-access-key" SAUCE_REGION="<us-west|eu-central>" SAUCE_TUNNEL_NAME="my-tunnel-name" \
docker run \
-e SAUCE_USERNAME=${SAUCE_USERNAME} \
-e SAUCE_ACCESS_KEY=${SAUCE_ACCESS_KEY} \
-e SAUCE_REGION=${SAUCE_REGION} \
-e SAUCE_TUNNEL_NAME=${SAUCE_TUNNEL_NAME} \
--network="host" \
-it saucelabs/sauce-connect:5.0
```
If desired, you can specify any additional [`sc run` options](/dev/cli/sauce-connect-5/run/) as environment variables.
Check this list of [supported tags](https://hub.docker.com/r/saucelabs/sauce-connect/tags?&ordering=&name=5.).

## Configure and run

Sauce Connect Proxy can be configured using:

* Configuration file,
* Environment variables,
* Command line arguments.

All of these options are supported in containers, and you can use them interchangeably.

### Configuration file

To use a configuration file, mount the file to the container at `/etc/sauce-connect/sauce-connect.yaml`.

<Tabs defaultValue="docker" values={[{label: 'docker', value: 'docker'},{label: 'docker compose', value: 'docker compose'}]}>

<TabItem value="docker">

```bash
docker run \
-v /path/to/config.yaml:/etc/sauce-connect/sauce-connect.yaml \
saucelabs/sauce-connect
```

</TabItem>

<TabItem value="docker compose">

```yaml
services:
sc:
image: saucelabs/sauce-connect
volumes:
- /path/to/config.yaml:/etc/sauce-connect/sauce-connect.yaml:ro
```

</TabItem>

</Tabs>

### Environment variables

You can also configure Sauce Connect Proxy using environment variables.
The following example demonstrates how to run the container using environment variables.

<Tabs defaultValue="docker" values={[{label: 'docker', value: 'docker'},{label: 'docker compose', value: 'docker compose'}]}>

<TabItem value="docker">

```bash
docker run \
-e SAUCE_USERNAME="<usename>" \
-e SAUCE_ACCESS_KEY="<access-key>" \
-e SAUCE_REGION="<region>" \
-e SAUCE_TUNNEL_NAME="<tunnel-name>" \
saucelabs/sauce-connect
```

</TabItem>

<TabItem value="docker compose">

```yaml
services:
sc:
image: saucelabs/sauce-connect
environment:
SAUCE_USERNAME: <usename>
SAUCE_ACCESS_KEY: <access-key>
SAUCE_REGION: <region>
SAUCE_TUNNEL_NAME: <tunnel-name>
```

</TabItem>

</Tabs>

### Command line arguments

To pass command line arguments, use the `sc` command followed by the desired arguments.

<Tabs defaultValue="docker" values={[{label: 'docker', value: 'docker'},{label: 'docker compose', value: 'docker compose'}]}>

<TabItem value="docker">

```bash
docker run saucelabs/sauce-connect run \
--username=<username> \
--access-key=<access-key> \
--region=<region> \
--tunnel-name=<tunnel-name>
```

</TabItem>

<TabItem value="docker compose">

```yaml
services:
sc:
image: saucelabs/sauce-connect
command: run --username=<username> --access-key=<access-key> --region=<region> --tunnel-name=<tunnel-name>
```

</TabItem>

</Tabs>

### Mix and match

It is also possible to mix and match the configuration options.
For instance, you can use a configuration file for all the common settings and override some of them using environment variables.
The order of precedence is as follows:

1. Command line arguments
1. Environment variables
1. Configuration file

The following example demonstrates how to use a configuration file and provide username and access key using environment variables.

<Tabs defaultValue="docker" values={[{label: 'docker', value: 'docker'},{label: 'docker compose', value: 'docker compose'}]}>

<TabItem value="docker">

```bash
docker run \
-e SAUCE_USERNAME="<usename>" \
-e SAUCE_ACCESS_KEY="<access-key>" \
-v /path/to/config.yaml:/etc/sauce-connect/sauce-connect.yaml \
saucelabs/sauce-connect
```

</TabItem>

<TabItem value="docker compose">

```yaml
services:
sc:
image: saucelabs/sauce-connect
environment:
SAUCE_USERNAME: <usename>
SAUCE_ACCESS_KEY: <access-key>
volumes:
- /path/to/config.yaml:/etc/sauce-connect/sauce-connect.yaml:ro
```

</TabItem>

</Tabs>

## Logs

Logs are handled automatically by Docker, and you can use the `docker logs` command to access them.
To access logs:

Alternatively, you can also mount a config file to the container by adding the `-v` option to the `docker run` command.
1. Find the container ID.

```bash
$ docker run \
-v /path/to/config.yaml:/etc/sauce-connect/sauce-connect.yaml \
--network="host"\
-it saucelabs/sauce-connect:5.0
docker ps
```
3. To access logs, use the `docker logs` command.
1. Use the container ID to get the logs.

```bash
$ docker logs <container-id>
docker logs <container-id>
```

See [Sauce Connect Proxy Readiness Checks](/secure-connections/sauce-connect-5/operation/readiness-checks) for more information on how to check if the tunnel is ready to accept jobs.
## Health checks

:::note
The example above uses `--network="host"` docker option to allow Sauce Connect in the Docker container to access your local services in the host machine. This option does not work on MacOS and Windows. See [Connect from a container to a service on the macOS host](https://docs.docker.com/desktop/networking/#use-cases-and-workarounds) for more details.
:::
The docker container has a built-in health check that can be used to determine if the tunnel is ready to accept jobs.
You should see the container status as `healthy` in `docker ps` when the tunnel is ready.
See [Sauce Connect Proxy Readiness Checks](/secure-connections/sauce-connect-5/operation/readiness-checks) for more information.

## Additional Resources

- [Sauce Connect Proxy Readiness Checks](/secure-connections/sauce-connect-5/operation/readiness-checks)
- [Use host networking in Docker](https://docs.docker.com/network/host/)
- [Connect from a container to a service on the macOS host](https://docs.docker.com/desktop/mac/networking/#use-cases-and-workarounds)
- [Docker Compose File](https://docs.docker.com/compose/compose-file/compose-file-v3/)