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.

Prerequisites

• 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 https://raw.githubusercontent.com/gravitational/teleport/v12.1.1/docker/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

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

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
ssh [email protected]

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

From term container
ssh [email protected]

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 127.0.0.1:3022 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:
https://proxy.luna.teleport:443/web/invite/your-token-here
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.

Next steps

• Learn about Teleport Server Access.
• Learn about Teleport Access Controls.
• Get started with Teleport Session Recording.
• Try out one of our Database Access Guides.
• For Kubernetes environments, try out one of our Helm Guides.

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:

[defaults]
host_key_checking = True
inventory=/etc/teleport.d/ansible/hosts
remote_tmp=/tmp

[ssh_connection]
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/teleport.pub
HostKey /mnt/shared/certs/mars.openssh.teleport
HostCertificate /mnt/shared/certs/mars.openssh.teleport-cert.pub

Teleport's user and role used for bot access:

kind: role
version: v5
metadata:
  name: bot
spec:
  # SSH options used for user sessions
  options:
    # 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.
  allow:
    logins: ['root']
    node_labels:
      '*': '*'
---
kind: user
version: v2
metadata:
  name: bot
spec:
  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\ // > ./teleport.pub
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/ > ./teleport-known_hosts.pub
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;