Fork me on GitHub
Teleport

Run Teleport using Docker

This section will cover:

  • Getting started with a local Teleport using Docker.
  • Using Teleport with Teleport's native client, tsh.

Prerequisites

  • Teleport v7.1.2 Open Source or Enterprise.
  • Docker v20.10.7 or later.
docker version

Client: Docker Engine - Community

Version: 20.10.7

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.

Note
You will need a recent version of Docker installed to follow this section of the quick start guide. We currently only offer Docker images for x86_64 architectures.

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:7.0The latest version of Teleport Open Source 7.0YesUbuntu 20.04
quay.io/gravitational/teleport:7.1.2The version specified in the image's tag (i.e. 7.1.2)NoUbuntu 20.04

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

Step 2/4. Start teleport

Create teleport configs and start the process with sample 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:7 -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:7

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 operating system user root or ubuntu:

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:

  1. Open the URL in Safari.
  2. Use the Chrome flag --ignore-certificate-errors instead.

Both options will allow you to open the Web UI and continue with the Quickstart.

Step 4/4. tsh into your Teleport container

Finish signing up and creating your user using the generated link created previously.

Download and install a copy of Teleport locally. Doing so will install the tsh tool so you can interact with Docker containers.

Open a second terminal and issue the command:

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:              admin
  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 localhost (running in your Docker container) issue the following tsh command:

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