Sign In

Sign in to Teleport

Teleport Cloud LoginLogin to your Teleport AccountDashboard LoginLegacy Login & Teleport Enterprise Downloads
Get Started
Fork me on GitHub

Teleport

Run Teleport using Docker

Version 12.x
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.
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.
  • A Teleport Enterprise account. If you do not have one, use our signup form to schedule a demo with the Teleport Sales Team.
  • Docker v20.10.7 or later.
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 amd64, arm, and arm64 Docker images for every version of Teleport.

These images are hosted on Amazon ECR Public. All tags under public.ecr.aws/gravitational/teleport are Teleport Open Source images. You can specify the architecture of a Teleport Docker image by adding a postfix to the image tag, e.g., public.ecr.aws/gravitational/teleport:12-arm64. Versions without an architecture postfix use the amd64 architecture, e.g., public.ecr.aws/gravitational/teleport:12.

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
public.ecr.aws/gravitational/teleport:12The latest version of Teleport Open SourceYesUbuntu 20.04
public.ecr.aws/gravitational/teleport:12.1.1The version specified in the image's tag (i.e. 12.1.1)NoUbuntu 20.04

For testing, we always recommend that you use the latest released version of Teleport, which is currently public.ecr.aws/gravitational/teleport:12.1.1.

We provide pre-built amd64, arm, and arm64 Docker images for every version of Teleport Enterprise.

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.

These images are hosted on our Amazon ECR Public repository. All tags under public.ecr.aws/gravitational/teleport-ent are Teleport Enterprise images. You can specify the architecture of a Teleport Docker image by adding a postfix to the image tag, e.g., public.ecr.aws/gravitational/teleport:12-arm64. Versions without an architecture postfix use the amd64 architecture, e.g., public.ecr.aws/gravitational/teleport:12.

Image nameOpen Source or Enterprise?Teleport versionImage automatically updated?Image base
public.ecr.aws/gravitational/teleport-ent:12EnterpriseThe latest version of Teleport Enterprise 12YesUbuntu 20.04
public.ecr.aws/gravitational/teleport-ent:12-fipsEnterprise FIPSThe latest version of Teleport Enterprise 12 FIPSYesUbuntu 20.04
public.ecr.aws/gravitational/teleport-ent:12.1.1EnterpriseThe version specified in the image's tag (i.e. 12.1.1)NoUbuntu 20.04
public.ecr.aws/gravitational/teleport-ent:12.1.1-fipsEnterprise FIPSThe version specified in the image's tag (i.e. 12.1.1)NoUbuntu 20.04

For testing, we always recommend that you use the latest release version of Teleport Enterprise, which is currently public.ecr.aws/gravitational/teleport-ent:12.1.1.

Step 2/4. Start Teleport

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

Docker image to use. The default is the amd64 version. Add -arm64 or -arm
to the end (ex: public.ecr.aws/gravitational/teleport:12.1.1-arm64 to get the arm versions.
TELEPORT_DOCKER_IMAGE=public.ecr.aws/gravitational/teleport:12.1.1
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 \  ${TELEPORT_DOCKER_IMAGE} -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 \  ${TELEPORT_DOCKER_IMAGE}

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

The teleport binary reads a local license file to authenticate your Teleport Enterprise account.

To obtain your license file, visit the Teleport customer dashboard and log in. Click "DOWNLOAD LICENSE KEY". You will see your current Teleport Enterprise account permissions and the option to download your license file:

License File modal

Move your license.pem file to ~/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 \  public.ecr.aws/gravitational/teleport-ent:12.1.1 -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 \  public.ecr.aws/gravitational/teleport-ent:12.1.1

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, click "Advanced" then "Proceed to URL".
    • If a server previously accessible from this URL set an HTTP Strict Transport Security (HSTS) header, the "Proceed to" link will not display. Type thisisunsafe to ignore the HSTS header and proceed.

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 Teleport 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

Have a suggestion or can’t find something?
IMPROVE THE DOCS