docs: update docker guide to allow for server access and show troubleshooting

docs/pages/includes/docker-images-oss.mdx

@@ -1,5 +1,6 @@
 We provide a pre-built multi-arch Docker image for every version of Teleport,
-including images for `amd64`, `arm`, and `arm64` architectures.
+including images for `amd64`, `arm`, and `arm64` architectures. Our images contain only Teleport binaries
+and their application dependencies.
 
 These images are hosted on Amazon ECR Public. All tags under `public.ecr.aws/gravitational/teleport-distroless` [are Teleport Open Source images](https://gallery.ecr.aws/gravitational/teleport-distroless).
 

docs/pages/includes/enterprise/docker-images.mdx

@@ -1,13 +1,21 @@
-This table gives an idea of how our image naming scheme works. We offer images which point to a static version of Teleport Enterprise, as well as images which are
-automatically rebuilt every night. 
+This table gives an idea of how our image naming scheme works. We offer images
+which point to a static version of Teleport Enterprise, as well as images which are
+automatically rebuilt every night.  Our images contain only Teleport binaries and their application dependencies.
 
-Nightly images point to the latest version of Teleport Enterprise from the three most recent release branches.
-They are stable, and we recommend their use to easily keep your Teleport Enterprise installation up to date.
+Nightly images point to the latest version of Teleport Enterprise from the three
+most recent release branches. They are stable, and we recommend their use to easily
+keep your Teleport Enterprise installation up to date.
 
-These images are hosted on our [Amazon ECR Public repository](https://gallery.ecr.aws/gravitational/teleport-ent-distroless). All tags under `public.ecr.aws/gravitational/teleport-ent-distroless` are Teleport Enterprise images. Each tag points to a multi-arch image, containing Teleport for `arm`, `arm64` and `amd64`.
+These images are hosted on our [Amazon ECR Public repository](https://gallery.ecr.aws/gravitational/teleport-ent-distroless).
+All tags under `public.ecr.aws/gravitational/teleport-ent-distroless` are
+Teleport Enterprise images. Each tag points to a multi-arch image, containing
+Teleport for `arm`, `arm64` and `amd64`.
 
 FIPS images are still posted to our [Legacy Amazon ECR Public repository](https://gallery.ecr.aws/gravitational/teleport-ent).
-You can specify the architecture of a Teleport FIPS Docker image by adding a postfix to the image tag, e.g., `public.ecr.aws/gravitational/teleport:(=teleport.major_version=)-arm64`. Versions without an architecture postfix use the `amd64` architecture, e.g., `public.ecr.aws/gravitational/teleport:(=teleport.major_version=)`. 
+You can specify the architecture of a Teleport FIPS Docker image by adding a
+postfix to the image tag, e.g., `public.ecr.aws/gravitational/teleport:(=teleport.major_version=)-arm64`.
+Versions without an architecture postfix use the `amd64` architecture, e.g.,
+`public.ecr.aws/gravitational/teleport:(=teleport.major_version=)`. 
 
 | Image name | Open Source or Enterprise? | Teleport version | Image automatically updated? | Includes troubleshooting tools | Image base |
 | - | - | - | - | - | - |
@@ -18,10 +26,12 @@ You can specify the architecture of a Teleport FIPS Docker image by adding a pos
 | `(=teleport.latest_ent_debug_docker_image=)` | Enterprise | The version specified in the image's tag (i.e. (=teleport.version=)) | No | Yes | [Distroless Debian 11](https://github.com/GoogleContainerTools/distroless) |
 | `(=teleport.latest_ent_docker_image=)-fips` | Enterprise FIPS | The version specified in the image's tag (i.e. (=teleport.version=)) | No | Yes | [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu) |
 
-For testing, we always recommend that you use the latest release version of Teleport Enterprise, which is currently `(=teleport.latest_ent_docker_image=)`.
+For testing, we always recommend that you use the latest release version of
+Teleport Enterprise, which is currently `(=teleport.latest_ent_docker_image=)`.
 
 [Ubuntu 20.04](https://hub.docker.com/\_/ubuntu)-based images for non-FIPS 
 Teleport are available from our [Legacy Amazon ECR Public repository](https://gallery.ecr.aws/gravitational/teleport-ent).
 
-The `*-debug` images include a Busybox shell and tool suite in addition to Teleport, and are intended for troubleshooting deployments only. They are not intended for production use.
+The `*-debug` images include a Busybox shell and tool suite in addition to Teleport,
+and are intended for troubleshooting deployments only. They are not intended for production use.
 

docs/pages/management/guides/docker.mdx

@@ -7,13 +7,9 @@ h1: Run Teleport using Docker
 This guide will explain how to run a container using one of Teleport's Docker
 images and execute commands on that container via Teleport's `tsh` client.
 
-<Notice scope={["cloud"]} type="tip">
-
 Since all of Teleport's services are run from the same binary, you can
-use our Docker image to run Node services (e.g., the Database Service or App
-Service) or explore the Auth and Proxy Services locally.
-
-</Notice>
+use our Docker image to run Teleport services (e.g., the Database Service or Application
+Service) or explore the Auth and Proxy Services locally. In this guide, we will also show you how to join a server (in this case, an Ubuntu container) to your local Dockerized Teleport cluster.
 
 ## Prerequisites
 
@@ -22,11 +18,11 @@ Service) or explore the Auth and Proxy Services locally.
 
 - Docker v(=docker.version=) or later.
 
-```code
-$ docker version
-# Client: Docker Engine - Community
-# Version:           (=docker.version=)
-```
+  ```code
+  $ docker version
+  # Client: Docker Engine - Community
+  # Version:           (=docker.version=)
+  ```
 
 - The `tsh` client tool, which ships with the `teleport` binary. Visit [Download Teleport](https://goteleport.com/download/) to download `tsh`.
 
@@ -36,13 +32,14 @@ $ docker version
 - A Teleport Enterprise account. If you do not have one, use our [signup
   form](https://goteleport.com/signup/enterprise/) to schedule a demo with the
   Teleport Sales Team.
+
 - Docker v(=docker.version=) or later.
 
-```code
-$ docker version
-# Client: Docker Engine - Community
-# Version:           (=docker.version=)
-```
+  ```code
+  $ docker version
+  # Client: Docker Engine - Community
+  # Version:           (=docker.version=)
+  ```
 
 - The `tsh` client tool, which ships with the `teleport` binary. Visit the [customer portal](https://dashboard.gravitational.com/web/login) to download Teleport.
 
@@ -81,12 +78,12 @@ $ mkdir -p ~/teleport/config ~/teleport/data
 # This container will write the config and immediately exit--this is expected.
 $ docker run --hostname localhost --rm \
   --entrypoint=/usr/local/bin/teleport \
-  ${TELEPORT_DOCKER_IMAGE} configure > ~/teleport/config/teleport.yaml
+  ${TELEPORT_DOCKER_IMAGE} configure --roles=proxy,auth > ~/teleport/config/teleport.yaml
 # Start Teleport with mounted config and data directories, plus all ports
 $ docker run --hostname localhost --name teleport \
   -v ~/teleport/config:/etc/teleport \
   -v ~/teleport/data:/var/lib/teleport \
-  -p 3023:3023 -p 3025:3025 -p 3080:3080 \
+  -p 3025:3025 -p 3080:3080 \
   ${TELEPORT_DOCKER_IMAGE}
 ```
 
@@ -106,6 +103,7 @@ $ TELEPORT_DOCKER_IMAGE=(=teleport.latest_ent_docker_image=)
 # into the container.
 $ mkdir -p ~/teleport/config ~/teleport/data
 ```
+
 (!docs/pages/includes/enterprise/obtainlicense.mdx!)
 
 Move your `license.pem` file to `~/teleport/data`.
@@ -115,12 +113,12 @@ Move your `license.pem` file to `~/teleport/data`.
 # This container will write the config and immediately exit--this is expected.
 $ docker run --hostname localhost --rm \
   --entrypoint=/usr/local/bin/teleport \
-  ${TELEPORT_DOCKER_IMAGE} configure > ~/teleport/config/teleport.yaml
+  ${TELEPORT_DOCKER_IMAGE} configure --roles=proxy,auth > ~/teleport/config/teleport.yaml
 # Start Teleport with mounted config and data directories, plus all ports
 $ docker run --hostname localhost --name teleport \
   -v ~/teleport/config:/etc/teleport \
   -v ~/teleport/data:/var/lib/teleport \
-  -p 3023:3023 -p 3025:3025 -p 3080:3080 \
+  -p 3025:3025 -p 3080:3080 \
   ${TELEPORT_DOCKER_IMAGE}
 ```
 
@@ -149,18 +147,116 @@ The Web UI will be available at the displayed URL.
 
 (!docs/pages/includes/insecure-certificate.mdx!)
 
-## Step 4/4. tsh into your Teleport container
+## Step 4/4. Try server access
+
+The Teleport container we spun up earlier runs the Teleport Proxy and Auth Services.  You can try
+accessing a server through Teleport by installing the Teleport SSH Service
+on an Ubuntu Docker container. Here are the steps.
+
+First start an Ubuntu container:
+
+```code
+$ docker run -it --name=example-server --hostname=example-server ubuntu:latest bash
+```
+After you start your shell within the Ubuntu container, run the following commands to install the Teleport SSH Service:
+<Tabs>
+<TabItem scope={["oss"]} label="Open Source">
+
+```code
+# Docker container will start and you can install Teleport
+$ apt update && apt install curl -y
+# Download Teleport's PGP public key
+
+$ curl https://apt.releases.teleport.dev/gpg \
+-o /usr/share/keyrings/teleport-archive-keyring.asc
+# Source variables about OS version
+
+$ source /etc/os-release
+# Add the Teleport APT repository for v12. You'll need to update this
+# file for each major release of Teleport.
+# Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE'
+# and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'.
+# Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67
+
+$ echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \
+https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v12" \
+| tee /etc/apt/sources.list.d/teleport.list > /dev/null
+$ apt-get update
+$ apt-get install teleport
+```
+
+</TabItem>
+<TabItem scope={["enterprise", "cloud"]} label="Enterprise">
+
+```code
+# Docker container will start and you can install Teleport
+$ apt update && apt install curl -y
+# Download Teleport's PGP public key
+
+$ curl https://apt.releases.teleport.dev/gpg \
+-o /usr/share/keyrings/teleport-archive-keyring.asc
+# Source variables about OS version
+
+$ source /etc/os-release
+# Add the Teleport APT repository for v12. You'll need to update this
+# file for each major release of Teleport.
+# Note: if using a fork of Debian or Ubuntu you may need to use '$ID_LIKE'
+# and the codename your distro was forked from instead of '$ID' and '$VERSION_CODENAME'.
+# Supported versions are listed here: https://github.com/gravitational/teleport/blob/master/build.assets/tooling/cmd/build-os-package-repos/runners.go#L42-L67
+
+$ echo "deb [signed-by=/usr/share/keyrings/teleport-archive-keyring.asc] \
+https://apt.releases.teleport.dev/${ID?} ${VERSION_CODENAME?} stable/v12" \
+| tee /etc/apt/sources.list.d/teleport.list > /dev/null
+$ apt-get update
+$ apt-get install teleport-ent
+```
+
+</TabItem>
+</Tabs>
+
+Keep the Docker `example-server` terminal running and run a separate command
+in another terminal to create a join token that the Teleport SSH Service will use to establish trust with your Teleport cluster:
+
+```code
+$ docker exec teleport tctl nodes add
+# The invite token: 02adc78db14c4958a94a78e216fba689
+# This token will expire in 30 minutes.
+
+# Run this on the new node to join the cluster:
+
+# > teleport start \
+   --roles=node \
+   --token=02adc78db14c4958a94a78e216fba689 \
+   --ca-pin=sha256:51c0e24825fae3133da0d8659f4dd533808e2dc92c000b577c8725b6cbcb66ae \
+   --auth-server=172.17.0.2:3025
 
-After you have finished creating your user, open a second terminal and issue the
-command, which will log in to your Teleport cluster via the Proxy Service at
+# Please note:
+
+#   - This invitation token will expire in 30 minutes
+#   - 172.17.0.2:3025 must be reachable from the new node
+  ```
+
+Copy the full `teleport start` command and run it in the `example-server` Docker container shell.
+
+Open another terminal window and confirm that you joined the SSH Service to the cluster
+ with `tctl nodes ls` on the `teleport` container.
+
+```code
+$ docker exec teleport tctl nodes ls
+# Host           UUID                Public Address  Labels Version
+# -------------- ------------------- --------------- ------ -------
+# example-server edc6b7ae-0ae5-43... 172.17.0.3:3022        12.2.2
+```
+
+Issue this command, which will log in to your Teleport cluster via the Proxy Service at
 `localhost`.
 
 ```code
 $ tsh login --proxy=localhost --insecure --user=testuser
 ```
 
 <Admonition type="note" title="Note">
-  The `--insecure` flag is not recommended in production but can be used to bypass certain TLS and port requirements when testing locally.
+The `--insecure` flag is not recommended in production but can be used to bypass certain TLS and port requirements when testing locally.
 </Admonition>
 
 You will be prompted to enter the password and One-Time Passcode you created for your user `testuser`:
@@ -173,7 +269,7 @@ Enter your OTP token:
 
 After successfully authenticating you should see the following in your terminal:
 
-```
+```text
 WARNING: You are using insecure connection to Teleport proxy https://localhost:3080
 > Profile URL:        https://localhost:3080
   Logged in as:       testuser
@@ -189,22 +285,88 @@ Running the next command will display all Teleport Nodes you're connected to:
 
 ```code
 $ tsh ls
-
-# Node Name Address        Labels                          
-# --------- -------------- ------------------------------- 
-# localhost 127.0.0.1:3022 env=example, hostname=localhost 
+# Node Name      Address         Labels
+# -------------- --------------- ------
+# example-server 172.17.0.3:3022
 ```
 
-To SSH into the local Node called `localhost`:
+To SSH into the local container called `example-server`:
 
 ```code
-$ tsh ssh root@localhost
+$ tsh ssh root@example-server
 ```
 
 This will bring up the Linux command prompt where you can issue Bash commands, traverse the directory tree, and explore the container contents:
 
 ```txt
-root@localhost:~# 
+root@example-server:~# 
+```
+
+After exiting the session you can replay the interaction from the command line:
+
+```code
+$ tsh recordings ls
+# ID                                   Type Participants Hostname       Timestamp
+# ------------------------------------ ---- ------------ -------------- ------------------------
+# 1da4faa9-01e9-4241-875f-4143f302c9c4 ssh  testuser     example-server Apr 13 2023 16:46:59 UTC
+$ tsh play 1da4faa9-01e9-4241-875f-4143f302c9c4
+```
+
+## Troubleshooting
+
+Teleport provides a container image that includes a Busybox shell. This image is not intended
+for production. You will need to stop the non-debug container and start again with the
+debug version to use.
+
+```code
+# Stop teleport container
+$ docker stop teleport
+# Remove teleport container so another can be started with the same name
+$ docker rm teleport
+```
+
+<Tabs>
+<TabItem scope={["oss"]} label="Open Source">
+
+Use the debug image with the same data and configuration.
+
+```code
+# Debug Docker image to use. Defaults to the host architecture. Use the `--platform`
+# option in `docker run` to override.
+$ TELEPORT_DOCKER_IMAGE=(=teleport.latest_oss_debug_docker_image=)
+# Start Teleport with mounted config and data directories, plus all ports
+$ docker run --hostname localhost --name teleport \
+  -v ~/teleport/config:/etc/teleport \
+  -v ~/teleport/data:/var/lib/teleport \
+  -p 3025:3025 -p 3080:3080 \
+  ${TELEPORT_DOCKER_IMAGE}
+```
+
+</TabItem>
+<TabItem scope={["enterprise", "cloud"]} label="Enterprise">
+
+Use the debug image with the same data and configuration.
+
+```code
+# Debug Docker image to use. Defaults to the host architecture. Use the `--platform`
+# option in `docker run` to override.
+$ TELEPORT_DOCKER_IMAGE=(=teleport.latest_ent_debug_docker_image=)
+# Start Teleport with mounted config and data directories, plus all ports
+$ docker run --hostname localhost --name teleport \
+  -v ~/teleport/config:/etc/teleport \
+  -v ~/teleport/data:/var/lib/teleport \
+  -p 3025:3025 -p 3080:3080 \
+  ${TELEPORT_DOCKER_IMAGE}
+```
+
+</TabItem>
+</Tabs>
+
+Now you can open a `sh` shell within the Docker container to perform any troubleshooting.
+
+```code
+$ docker exec -it teleport sh
+$ tctl status
 ```
 
 ## Next steps