Skip to main content
Version: 19.x (unreleased)

Installing Teleport on Docker

Report an IssueView as Markdown

This guide shows you how to install and run Teleport using the official Docker images. It covers selecting an image, configuring the container, running Teleport services, and upgrading.

Images​

Teleport publishes a pre-built Docker image for every release. Images are hosted on Amazon ECR Public.

Image suffixes​

You can specify attributes of an image by appending a suffix to the repository name or tag.

Images with the -distroless suffix include only the teleport binary and its runtime dependencies, with no shell or utility applications. An example is public.ecr.aws/gravitational/teleport-distroless for Teleport Community Edition.

Images with the -distroless-debug suffix include a Busybox shell and tool suite in addition to Teleport, and are intended for troubleshooting deployments only. They are not intended for production use. An example is public.ecr.aws/gravitational/teleport-distroless-debug.

-distroless and -distroless-debug images support multiple architectures natively, and do not require (or support) image suffixes. You can specify an architecture using the --platform flag of docker pull to pull the arm, arm64, or amd64 version of an image.

Version tags​

Images point to a static version of Teleport. Use the image's tag to specify either:

  • The major, minor, and patch version (e.g., 19.0.0-dev for the latest version of Teleport Community Edition).
  • The major version only, which implies the latest minor and patch numbers for that major version. For example, 19 implies 19.0.0-dev.
Image nameIncludes troubleshooting toolsImage base
public.ecr.aws/gravitational/teleport-ent-distroless:18.8.3NoDistroless Debian 12
public.ecr.aws/gravitational/teleport-ent-distroless-debug:18.8.3YesDistroless Debian 12

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

Interacting with distroless images​

Teleport images are based on Google's Distroless images. These images do not contain a shell.

To execute Teleport commands on containers based on these images, run commands similar to the following:

in docker
docker exec -it teleport-container tctl status

in Kubernetes
kubectl exec -i pod-name -- tctl status

sending local files via stdin
kubectl exec -i pod-name -- tctl create -f < my-local-file.yaml

retrieving the teleport service config file from the configmap
kubectl get configmap teleport-cluster-auth -o jsonpath="{.data['teleport\.yaml']}"

retrieving output via stdout and tar
kubectl exec -i pod-name -- tctl auth sign --user admin --format tls --ttl 10m --tar -o admin | tar xv -C local
ls -l local
total 24-rw-------  1 trent  staff  1318 Jul 24 15:52 admin.cas-rw-------  1 trent  staff  1895 Jul 24 15:52 admin.crt-rw-------  1 trent  staff  1679 Jul 24 15:52 admin.key

Alternatively, you can use the debug variant of the image, which contains busybox and a minimal shell invocable via busybox sh:

docker run -it --entrypoint="" public.ecr.aws/gravitational/teleport-distroless-debug:13.3.7 busybox sh

Machine & Workload Identity (tbot) image​

We also provide a slimmed-down distroless image that contains only the tbot binary for use with Teleport Machine & Workload Identity.

Image nameFIPS supportImage base
public.ecr.aws/gravitational/tbot-distroless:19.0.0-devNoDistroless Debian 12
public.ecr.aws/gravitational/tbot-fips-distroless:19.0.0-devYesDistroless Debian 12

The version tagging follows the same pattern as the main teleport-distroless image.

While the teleport-distroless image also includes tbot, prefer the tbot-specific image for Machine & Workload Identity deployments. This image is smaller, which improves pull times, and has a smaller attack surface. The image is also customized to improve the experience of running tbot in a container environment.

To learn more, read the Deploying Machine & Workload Identity on Kubernetes guide.

Running Teleport on Docker​

When running a container from one of the images listed above, treat the container as equivalent to running the teleport binary directly. The Teleport container requires access to a file system and network ports.

Configuration​

While Teleport's default configuration path is /etc/teleport.yaml, the Docker image is configured to read from /etc/teleport/teleport.yaml. Mount your configuration directory to /etc/teleport in the container so Teleport can find it.

Data directory​

All Teleport processes read from and write to a data directory, which by default is /var/lib/teleport. Make sure the data directory is mounted to your Teleport container. If you do not mount persistent storage, cluster state is lost when the container is recreated.

License file​

If your Teleport Enterprise container runs the Auth Service, you will need to give it access to a license file at the path named in the configuration, which is /var/lib/teleport/license.pem by default. Make sure a license exists at this location in the Teleport container's data directory.

Other file paths​

Depending on the configuration settings you assign on your Teleport container, you will need to make sure that any file paths you name are mounted on the container.

For example, if you are running the Teleport Proxy Service on a container, mount the directory containing TLS credentials to your Teleport container, then assign the following fields in the container's configuration file to the appropriate paths:

proxy_service:
  https_keypairs:
  - key_file: /my/path/key.pem
    cert_file: /my/path/cert.pem

See the Teleport Configuration Reference for whether a field you would like to assign requires a file path.

Ports​

A single Teleport process can run multiple services, each of which listens on a specific set of ports depending on your configuration. See our Networking Reference for the ports on your Teleport container to expose.

Extracting certificates from distroless images​

Extracting certificates created with tctl auth sign from a container running a distroless image can be tricky due to the absence of a shell and other OS tools.

Where possible, log into the Teleport cluster using tsh and use tctl auth sign locally to generate certificates. This way the action is logged against your Teleport user and is subject to all of the usual Teleport RBAC policies in your cluster.

If this is not possible, use tctl auth sign --tar to collect all the files generated by tctl auth sign into a tar archive, which is streamed directly to stdout. When you use --tar, the -o flag changes meaning: instead of writing files to disk, it acts as a name prefix for the entries inside the tar stream. As a result, no certificate files are written to the container filesystem. You can either pipe this output directly to tar, or redirect it to a local file for later use.

For example:

docker exec teleport-container \  tctl auth sign --user alice --format tls -o alice.local --tar | tar xv
x alice.local.crtx alice.local.keyx alice.local.cas

Example: running a Teleport container locally​

In this example, you will run the Teleport Auth Service and Proxy Service on a local Docker container using Teleport Community Edition.

Since this container uses a self-signed certificate, we do not recommend using this configuration to protect any infrastructure outside your workstation. You can, however, join other local Docker containers to it using the token method.

  1. Create directories in your home directory to mount to the container. The Teleport container will write its configuration and data to these directories:

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

  2. Run teleport configure from the Teleport container to generate a configuration file. This sets the container's name to localhost so your browser can trust the Proxy Service's self-signed TLS certificate:

    docker run --hostname localhost --rm \  --entrypoint=/usr/local/bin/teleport \  public.ecr.aws/gravitational/teleport-distroless:13.3.7 configure --roles=proxy,auth > ~/teleport/config/teleport.yaml

  3. Start Teleport on your container. This container runs both the Auth Service and Proxy Service in a single process for local testing:

    docker run --hostname localhost --name teleport \  -v ~/teleport/config:/etc/teleport \  -v ~/teleport/data:/var/lib/teleport \  -p 3025:3025 -p 3080:3080 \  public.ecr.aws/gravitational/teleport-distroless:13.3.7

  4. In a new terminal, confirm that the Teleport container's web API is functioning as intended:

    curl --insecure https://localhost:3080/webapi/ping | jq

    The command returns JSON describing the cluster, including server_version, cluster_name, and details for each service. The --insecure flag is required because Teleport is using a self-signed certificate. In production, provision TLS credentials to the Proxy Service from a trusted CA, e.g., Let's Encrypt.

    Checkpoint: The Teleport container's Web API is functioning as intended

    The command above returns a JSON document describing the cluster.

Upgrading Teleport on Docker​

To upgrade a Teleport container running on Docker:

  1. Back up the Teleport backend before upgrading. Major-version upgrades run schema migrations on the data directory that cannot be reversed by starting an older image. For backup procedures and supported upgrade paths, see Upgrading Teleport.

  2. Stop the container with docker stop teleport.

  3. Leave the container's data directory in place.

  4. Run a new container with an image based on a newer Teleport version, mounting the data directory as you did when running the container initially. As long as the data directory contains the same content as before the upgrade, the Teleport container does not need to re-join the cluster.

  5. Verify the upgraded version:

    curl --insecure https://localhost:3080/webapi/ping | jq '.server_version'

If the upgrade fails or the container doesn't start, see Container fails to start after upgrade below.

Troubleshooting​

The sections below cover common issues when running Teleport on Docker. Each section names a specific symptom so you can scan for what you are seeing.

Port already in use​

If docker run fails with bind: address already in use for ports 3025 or 3080, another process on the host is using those ports. Find the conflicting process with lsof -i :3080 (macOS or Linux), then either stop it or map Teleport to a different host port (for example, -p 3081:3080).

Configuration file not found​

If the container exits immediately with failed to read configuration or no such file or directory for /etc/teleport/teleport.yaml, the configuration file is not mounted into the container at the expected path. Verify that the configuration file exists on the host and that you mount its parent directory to /etc/teleport inside the container, not the file itself. Mounting a single file rather than its parent directory can cause issues when the file is replaced or symlinked.

Permission denied writing to the data directory​

If the container fails to start with permission denied errors against /var/lib/teleport, the container's user does not have write access to the mounted data directory. Distroless images run as a non-root user, so host directory permissions need to allow that user to write. Adjust permissions on the host directory with chmod or chown so the container's user can write to it.

tctl auth sign --tar produces no output​

If tctl auth sign --tar | tar xv runs but no certificate files appear locally, the underlying tctl auth sign call most likely failed and emitted an error message instead of a tar archive. You may also see tar: This does not look like a tar archive.

To diagnose, run tctl auth sign without the --tar flag and confirm that the user, format, and other parameters are valid. Once the command succeeds, add --tar back and pipe the output to tar xv.

Container fails to start after upgrade​

If the container fails to start after upgrading to a newer Teleport version, check the logs with docker logs teleport for migration or compatibility errors. Confirm that you did not skip a major version: Teleport supports upgrades from one major version to the next, and skipping versions is not supported.

Do not roll back by starting the previous image version against the upgraded data directory. Major-version upgrades run schema migrations that an older Auth Service cannot read, and doing so can leave the backend in an unusable state. To roll back safely, restore the backend from the backup taken before the upgrade. See Upgrading Teleport for the supported procedure.