Fork me on GitHub
Teleport

Run Teleport using Docker

Improve

This guide will explain how to run a container using one of Teleport's Docker images and execute commands on that container via Teleport's tsh client.

Since all of Teleport's services are run from the same binary, you can use our Docker image to run Node services (e.g., the Database Service or App Service) or explore the Auth and Proxy Services locally.

Prerequisites

  • Docker v20.10.7 or later. We currently only offer Docker images for x86_64 architectures.
docker version

Client: Docker Engine - Community

Version: 20.10.7

  • The tsh client tool, which ships with the teleport binary. Visit Download Teleport to download tsh.
  • Docker v20.10.7 or later. We currently only offer Docker images for x86_64 architectures.
docker version

Client: Docker Engine - Community

Version: 20.10.7

  • The tsh client tool, which ships with the teleport binary. Visit the customer portal to download Teleport.

Step 1/4. Pick your image

We provide pre-built Docker images for every version of Teleport.

These images are hosted on quay.io. All tags under quay.io/gravitational/teleport are Teleport Open Source images.

The table below gives an idea of how our image naming scheme works. We offer images that point to a static version of Teleport, as well as images that are automatically rebuilt every night. These nightly images point to the latest version of Teleport from the three most recent release branches. They are stable, and we recommend their use to keep your Teleport installation up to date.

Image nameTeleport versionImage automatically updated?Image base
quay.io/gravitational/teleport:9.1.2The latest version of Teleport Open Source 9.0YesUbuntu 20.04
quay.io/gravitational/teleport:9.2.3The version specified in the image's tag (i.e. 9.2.3)NoUbuntu 20.04

For testing, we always recommend that you use the latest release version of Teleport, which is currently quay.io/gravitational/teleport:9.1.2.

We provide pre-built Docker images for every version of Teleport.

This table gives an idea of how our image naming scheme works. We offer images which point to a static version of Teleport Enterprise, as well as images which are automatically rebuilt every night.

Nightly images point to the latest version of Teleport Enterprise from the three most recent release branches. They are stable, and we recommend their use to easily keep your Teleport Enterprise installation up to date.

Image nameOpen Source or Enterprise?Teleport versionImage automatically updated?Image base
quay.io/gravitational/teleport-ent:9.1.2EnterpriseThe latest version of Teleport Enterprise 9.0YesUbuntu 20.04
quay.io/gravitational/teleport-ent:9.1.2-fipsEnterprise FIPSThe latest version of Teleport Enterprise 9.0 FIPSYesUbuntu 20.04
quay.io/gravitational/teleport-ent:9.2.3EnterpriseThe version specified in the image's tag (i.e. 9.2.3)NoUbuntu 20.04
quay.io/gravitational/teleport-ent:9.2.3-fipsEnterprise FIPSThe version specified in the image's tag (i.e. 9.2.3)NoUbuntu 20.04

For testing, we always recommend that you use the latest release version of Teleport Enterprise, which is currently quay.io/gravitational/teleport-ent:9.1.2.

Step 2/4. Start Teleport

Create Teleport configs and start the process with the following docker run commands:

Create local config and data directories for Teleport, which will be mounted

into the container.

mkdir -p ~/teleport/config ~/teleport/data

Generate a sample Teleport config and write it to the local config directory.

This container will write the config and immediately exit--this is expected.

docker run --hostname localhost --rm \ --entrypoint=/bin/sh \ -v ~/teleport/config:/etc/teleport \ quay.io/gravitational/teleport:9.1.2 -c "teleport configure > /etc/teleport/teleport.yaml"

Start Teleport with mounted config and data directories, plus all ports

docker run --hostname localhost --name teleport \ -v ~/teleport/config:/etc/teleport \ -v ~/teleport/data:/var/lib/teleport \ -p 3023:3023 -p 3025:3025 -p 3080:3080 \ quay.io/gravitational/teleport:9.1.2

Create Teleport configs and start the process with the following docker run commands:

Create local config and data directories for Teleport, which will be mounted

into the container.

mkdir -p ~/teleport/config ~/teleport/data

Generate a sample Teleport config and write it to the local config directory.

This container will write the config and immediately exit--this is expected.

docker run --hostname localhost --rm \ --entrypoint=/bin/sh \ -v ~/teleport/config:/etc/teleport \ quay.io/gravitational/teleport-ent:9.1.2 bash -c "teleport configure > /etc/teleport/teleport.yaml"

Start Teleport with mounted config and data directories, plus all ports

docker run --hostname localhost --name teleport \ -v ~/teleport/config:/etc/teleport \ -v ~/teleport/data:/var/lib/teleport \ -p 3023:3023 -p 3025:3025 -p 3080:3080 \ quay.io/gravitational/teleport-ent:9.1.2

Step 3/4. Creating a Teleport user

To create a user inside your Teleport container, use docker exec.

This example command will create a Teleport user called testuser which is allowed to log in as either root or ubuntu on the host operating system:

docker exec teleport tctl users add testuser --roles=editor,access --logins=root,ubuntu,ec2-user

When you run this command, Teleport will output a URL that you must open to complete the user signup process:

User testuser has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h0m0s:
https://localhost:3080/web/invite/4f2718a52ce107568b191f222ba069f7
NOTE: Make sure localhost:3080 points at a Teleport proxy which users can access.

The Web UI will be available at the displayed URL.

Insecure Certificate Error

If you encounter an "Insecure Certificate Error" (or equivalent warning) that prevents the Teleport Web UI from opening, you can perform one of the following actions depending on your browser:

  • In Safari's "This Connection Is Not Private" page, click "Show Details," then click "visit this website."
  • In Firefox, click "Advanced" from the warning page, then click "Accept the Risk and Continue."
  • In Chrome's warning page, type thisisunsafe to ignore certificate validation for the Teleport Web UI.

Step 4/4. tsh into your Teleport container

After you have finished creating your user, open a second terminal and issue the command, which will log in to your Teleport cluster via the Proxy Service at localhost.

tsh login --proxy=localhost --insecure --user=testuser
Note

The --insecure flag is not recommended in production but can be used to bypass certain TLS and port requirements when testing locally.

You will be prompted to enter the password and One-Time Passcode you created for your user testuser:

Enter password for Teleport user testuser:
Enter your OTP token:
9999999

After successfully authenticating you should see the following in your terminal:

WARNING: You are using insecure connection to SSH proxy https://localhost:3080
> Profile URL:        https://localhost:3080
  Logged in as:       testuser
  Cluster:            localhost
  Roles:              editor, access
  Logins:             root, ubuntu
  Kubernetes:         disabled
  Valid until:        2021-06-10 07:15:42 -0500 CDT [valid for 12h0m0s]
  Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty

Running the next command will display all Teleport Nodes you're connected to:

tsh ls

Node Name Address Labels

--------- -------------- -------------------------------

localhost 127.0.0.1:3022 env=example, hostname=localhost

To SSH into the local Node called localhost:

This will bring up the Linux command prompt where you can issue Bash commands, traverse the directory tree, and explore the container contents:

Next steps