Fork me on GitHub

Get started with Docker Compose

This section will cover:

  • Getting started with a local Teleport cluster using docker compose.
  • Using Teleport with OpenSSH, ansible and Teleport's native client, tsh.


  • Teleport v7.1.3 Open Source or Enterprise.
  • Docker v20.10.7 or later and docker-compose v1.25.0 or later.
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

Start teleport demo lab using docker-compose

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 container with setup clients 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.

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.

Explore audit log, session recordings and other features of Teleport.

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.cfg that instructs 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 for used for bot access:

kind: role
version: v4
  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;

Have a suggestion or can’t find something?