Fork me on GitHub


Get started with Docker Compose


This guide will help you understand how Teleport works by spinning up a demo cluster on your local machine using Docker Compose. It will also show you how to use Teleport with OpenSSH, Ansible, and Teleport's native client, tsh.

Production deployments

This guide is intended as a local lab for educational purposes. If you would like to set up Teleport for production usage, please see:

Getting Started on a Linux Server


  • Docker v20.10.7 or later. The Teleport Docker image we use in the Docker Compose lab currently only supports x86_64 architectures.
  • docker-compose v1.25.0 or later (or the Compose plugin for Docker).
docker-compose version

docker-compose version 1.25.0, build unknown

docker version

Client: Docker Engine - Community

Version: 20.10.7

Step 1/3. Start demo lab

Let's use docker-compose to start Teleport demo lab - a configured local cluster:

Download the quick start file from our GitHub repo

curl -Lso teleport-lab.yml

Pull the latest image and start the teleport demo lab using docker-compose

docker-compose -f teleport-lab.yml pull && docker-compose -f teleport-lab.yml up -d

You can later stop the Teleport lab using:

docker-compose -f teleport-lab.yml down

Step 2/3. Explore CLI

Let's jump into the container and explore Teleport:

From your local terminal

docker exec -ti term /bin/bash

We will run all future commands from the term container.

Welcome to Teleport Lab. With Teleport you can access servers, databases and web apps in your cluster.

Let's Try a couple of commands to get started. Teleport speaks SSH. You can SSH into it using OpenSSH:

From term container

Teleport is a bastion server for your OpenSSH hosts. SSH into OpenSSH server and record all commands:

From term container

You can also run Ansible on Teleport Nodes and OpenSSH servers:

From term container

cd /etc/teleport.d/ansible && ansible all -m ping

Try Teleport's client command: tsh. It's like ssh, but with superpowers. Find all hosts matching label env=example and run hostname command:

From term container

tsh ssh [email protected]=example hostname

You can see Teleport's nodes registered in the cluster using tsh ls command:

From term container

tsh ls

Node Name Address Labels

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

luna.teleport env=example, hostname=luna

Step 3/3. Explore web UI

Create a Teleport user called testuser which is allowed to log in as either operating system user root or ubuntu.

From term container

tctl users add testuser --roles=editor,access --logins=root,ubuntu

Teleport will output a URL that you must open to complete the user sign-up process:

User "testuser" has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h:


NOTE: Make sure proxy.luna.teleport:443 points at a Teleport proxy which users can access.

Port 443 on the Teleport container is published to the local host, so you can access the invitation page at https://localhost/web/invite/your-token-here.

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.

Next steps

Under the hood

Let's unpack some of the setup that made the demo possible. Teleport's authentication is based on client certificates and certificate authorities.

Here is ~/.ssh/config, which instructs the ssh client to use Teleport as a bastion server:

## Hosts with openssh suffix are OpenSSH nodes listening on port 22 as usual
Host *.openssh.teleport
    ProxyCommand ssh -o "ForwardAgent yes" -p 3023 proxy.luna.teleport -s proxy:%h:22

# Hosts without openssh suffix are Teleport Nodes listening on port 3022
Host *.teleport !proxy.luna.teleport
    ProxyCommand ssh -o "ForwardAgent yes" -p 3023 proxy.luna.teleport -s proxy:%h:3022

Ansible is set up to use ssh config above:

host_key_checking = True

scp_if_ssh = True
ssh_args = -F /root/.ssh/config

OpenSSH server is set up to trust Teleport's CA and uses Teleport-issued host certificate:

TrustedUserCAKeys /mnt/shared/certs/
HostKey /mnt/shared/certs/mars.openssh.teleport
HostCertificate /mnt/shared/certs/

Teleport's user and role used for bot access:

kind: role
version: v5
  name: bot
  # SSH options used for user sessions
    # max_session_ttl defines the TTL (time to live) of SSH certificates
    # issued to the users with this role.
    max_session_ttl: 10h

  # allow section declares a list of resource/verb combinations that are
  # allowed for the users of this role. by default nothing is allowed.
    logins: ['root']
      '*': '*'
kind: user
version: v2
  name: bot
  roles: ['bot']

Our lab uses admin tool tctl to generate and export certs:

Exports user CA for OpenSSH to trust.

tctl auth export --type=user | sed s/cert-authority\ // > ./

Export host CA for SSH client to trust, update some hostnames match patterns

tctl auth export --type=host | sed s/*.teleport/luna.teleport,*.luna.teleport,*.openssh.teleport/ > ./

Creates a user and a role in Teleport

tctl create -f /etc/teleport.d/scripts/resources.yaml

Create SSH cert for bot user

tctl auth sign --user=bot --format=openssh --out=bot --overwrite --ttl=10h

Create SSH host cert for SSH node

tctl auth sign --host=mars.openssh.teleport --format=openssh --overwrite --out=mars.openssh.teleport

Adds generated certs to SSH agent on start

cd /mnt/shared/certs && /usr/bin/ssh-add bot;