Skip to main content
Set Up Teleport Community Edition in 5 Minutes | Step by Step
Set Up Teleport Community Edition in 5 Minutes | Step by Step

Length: 05:36

Version: 19.x (unreleased)

Run a Self-Hosted Demo Cluster

Report an issue with this page

See how a self-hosted Teleport deployment works by completing the tutorial below. This shows you how to spin up a single-instance Teleport cluster on a Linux server (or a Linux container running locally) using Teleport Community Edition. Once you deploy the cluster, you can configure RBAC, register resources, and protect your small-scale demo environments or home lab.

You can also get started right away with a production-ready Teleport cluster by signing up for a free trial of Teleport Enterprise Cloud.

How it works​

In this guide, we show you how to run the following Teleport services on a single Linux server:

  • Teleport Auth Service: The certificate authority for your cluster. It issues certificates and conducts authentication challenges. The Auth Service is typically inaccessible outside your private network.
  • Teleport Proxy Service: The cluster frontend, which handles user requests, forwards user credentials to the Auth Service, and communicates with Teleport instances that enable access to specific resources in your infrastructure.
  • Teleport SSH Service: An SSH server implementation that takes advantage of Teleport's short-lived certificates, sophisticated RBAC, session recording, and other features.

Prerequisites​

You will need the following to deploy a demo Teleport cluster. If your environment doesn't meet the prerequisites, you can get started with Teleport by signing up for a free trial of Teleport Enterprise Cloud.

If you want to get a feel for Teleport commands and capabilities without setting up any infrastructure, take a look at the browser-based Teleport Labs.

You can follow this guide with either a remote virtual machine (e.g., an Amazon EC2 instance) or a local Docker container. Make sure you have met the following requirements for your platform:

  • A Linux host with only port 443 open to ingress traffic. You must be able to install and run software on the host. Either configure access to the host via SSH for the initial setup (and open an SSH port in addition to port 443) or enter the commands in this guide into an Amazon EC2 user data script, Google Compute Engine startup script, or similar.

You must also have one of the following:

  • A registered domain name.
  • An authoritative DNS nameserver managed by your organization, plus an existing certificate authority. If using this approach, ensure that your browser is configured to use your organization's nameserver.

Finally, you will need a multi-factor authenticator app such as Authy, Google Authenticator, or 1Password.

Step 1/4. Configure DNS​

If you are following this guide with a local Docker container, you can skip to Step 2.

If you are following this guide with a virtual machine, set up two DNS A records, each pointing to the IP address of your Linux host. Assuming teleport.example.com is your domain name, set up records for:

DomainReason
teleport.example.comTraffic to the Proxy Service from users and services.
*.teleport.example.comTraffic to web applications registered with Teleport. Teleport issues a subdomain of your cluster's domain name to each application.

Step 2/4. Set up Teleport on your Linux host​

In this step, you will log into your Linux host, download the Teleport binary, generate a Teleport configuration file, and start the Teleport Auth Service, Proxy Service, and SSH Service on the host.

Install Teleport​

On your Linux host or container, run the following command to install the Teleport binary:

curl https://cdn.teleport.dev/install.sh | bash -s 19.0.0-dev

Configure Teleport​

Generate a configuration file for Teleport using the teleport configure command. This command requires information about a TLS certificate and private key.

The instructions depend on whether you are running Teleport on the public internet, a local container, or a private network:

Let's Encrypt verifies that you control the domain name of your Teleport cluster by communicating with the HTTPS server listening on port 443 of your Teleport Proxy Service.

You can configure the Teleport Proxy Service to complete the Let's Encrypt verification process when it starts up.

On the host where you will start the Teleport Auth Service and Proxy Service, run the following teleport configure command. Assign teleport.example.com to the domain name of your Teleport cluster and [email protected] to an email address used for notifications (you can use any domain):

sudo teleport configure -o file \    --acme --acme-email=[email protected] \    --cluster-name=teleport.example.com

Port 443 on your Teleport Proxy Service host must allow traffic from all sources.

Start Teleport​

  1. Start Teleport on your virtual machine or container by following the instructions below:

    Enable and start the Teleport systemd service:

    sudo systemctl enable teleport
    sudo systemctl start teleport

  2. Access the Teleport Web UI via HTTPS at the domain you created earlier at teleport.example.com and accept the terms of using Teleport Community Edition.

    If you are running Teleport on a local Docker container, visit https://localhost:3080.

    You should see a welcome screen similar to the following:

Step 3/4. Create a Teleport user and set up multi-factor authentication​

In this step, we'll create a new Teleport user, teleport-admin, which is allowed to log into SSH hosts as any of the principals root, ubuntu, or ec2-user.

  1. If you following this guide on a local container, open another terminal and access your container:

    docker exec -it <CONTAINER_ID> /bin/bash

  2. On your VM or container, run the following command (remove sudo if using a local container). tctl is a client tool for configuring the Teleport Auth Service:

    sudo tctl users add teleport-admin --roles=editor,access --logins=root,ubuntu,ec2-user

    The command prints a message similar to the following:

    User "teleport-admin" has been created but requires a password. Share this URL with the user to complete user setup, link is valid for 1h:
https://teleport.example.com:443/web/invite/123abc456def789ghi123abc456def78

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

    If using a local container, replace the host and port with localhost:3080.

  3. Visit the provided URL in order to create your Teleport user.

    OS User Mappings

    The users that you specify in the logins flag (e.g., root, ubuntu and ec2-user in our examples) must exist on your Linux host. Otherwise, you will get authentication errors later in this tutorial.

    If a user does not already exist, you can create it with adduser <login> or use host user creation.

    If you do not have the permission to create new users on the Linux host, run tctl users add teleport $(whoami) to explicitly allow Teleport to authenticate as the user that you have currently logged in as.

  4. Teleport enforces the use of multi-factor authentication by default. It supports one-time passwords (OTP) and multi-factor authenticators (WebAuthn). In this guide, you will need to enroll an OTP authenticator application using the QR code on the Teleport welcome screen.

Logging in via the CLI

In addition to Teleport's Web UI, you can access resources in your infrastructure via the tsh client tool.

Install tsh on your local workstation:

Download the signed macOS .pkg installer for Teleport, which includes tsh. In Finder double-click the pkg file to begin installation:

curl -O https://cdn.teleport.dev/teleport-19.0.0-dev.pkg
danger

Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

Log in to receive short-lived certificates from Teleport. Replace teleport.example.com with your Teleport cluster's public address as configured above:

tsh login --proxy=teleport.example.com --user=teleport-admin
> Profile URL:        https://teleport.example.com:443  Logged in as:       teleport-admin  Cluster:            teleport.example.com  Roles:              access, editor  Logins:             root, ubuntu, ec2-user  Kubernetes:         enabled  Valid until:        2022-04-26 03:04:46 -0400 EDT [valid for 12h0m0s]  Extensions:         permit-agent-forwarding, permit-port-forwarding, permit-pty

Step 4/4. Enroll your infrastructure​

Once you finish setting up your user, you will see your SSH server in the Teleport Web UI:

With Teleport, you can protect all of the resources in your infrastructure behind a single identity-aware access proxy, including servers, databases, applications, Kubernetes clusters, Windows desktops, and cloud provider APIs.

To enroll a resource with Teleport, visit the Web UI and click Enroll New Resource. The Web UI will show you the steps you can take to enroll your new resource.

Next step: deploy Teleport Agents​

Teleport Agents proxy traffic to infrastructure resources like servers, databases, Kubernetes clusters, cloud provider APIs, and Windows desktops.

Step 4 showed you how to install agents manually, and you can also launch agents and enroll resources with them using infrastructure-as-code tools. For example, you can use Terraform to declare a pool of Teleport Agents and configure them to proxy your infrastructure. Read Protect Infrastructure with Teleport to get started.