teleport/docs/pages/getting-started/docker-compose.mdx

---
title: Getting started with Teleport using Docker Compose
description: How to get started with Teleport Open Source Edition using Docker Compose locally.
h1: 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

- Teleport v(=teleport.version=) Open Source or Enterprise.
- Docker v(=docker.version=) or later and [`docker-compose`](https://docs.docker.com/compose/install/) v(=docker.compose.version=) or later.

```code
$ docker-compose version
# docker-compose version (=docker.compose.version=), build unknown

$ docker version
#Client: Docker Engine - Community
# Version:           (=docker.version=)
```

## Step 1/3. Start demo lab

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

```code
# Download the quick start file from our Github repo
$ curl -Lso teleport-lab.yml https://raw.githubusercontent.com/gravitational/teleport/v(=teleport.version=)/docker/teleport-lab.yml
# Start teleport demo lab using docker-compose
$ docker-compose -f teleport-lab.yml up -d
```

<Admonition type="note" title="Note">
You can later stop the Teleport lab using:

```code
$ docker-compose -f teleport-lab.yml down
```
</Admonition>

## Step 2/3. Explore CLI

Let's jump into container with setup clients and explore Teleport:

```code
# From your local terminal
$ docker exec -ti term /bin/bash
```

<Admonition type="note" title="Note">
We will run all future commands from the `term` container.
</Admonition>

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:

```code
# From term container
$ ssh root@luna.teleport
```

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

```code
# From term container
$ ssh root@mars.openssh.teleport
```

You can also run ansible on Teleport nodes and OpenSSH servers:

```code
# 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:

```code
# From term container
$ tsh ssh root@env=example hostname
```

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

```code
# 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`.

```code
# 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:

```code
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`.

(!docs/pages/includes/insecure-certificate.mdx!)

## Next steps

- Learn about [Teleport Server Access](../server-access/introduction.mdx).
- Learn about [Teleport Access Controls](../access-controls/getting-started.mdx).
- Get started with [Teleport Session Recording](../server-access/guides/bpf-session-recording.mdx).
- Try out one of our [Database Access Guides](../database-access/guides.mdx).
- For Kubernetes environments, try out one of our [Helm Guides](../kubernetes-access/helm/guides.mdx).

## 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:

```
[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 for used for bot access:

```yaml
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:

```code
# 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;
```