Add Troubleshooting guide

Signed-off-by: TomSweeneyRedHat <tsweeney@redhat.com>

Closes: #793
Approved by: mheon

2 files changed, 65 insertions, 6 deletions

diff --git a/README.md b/README.md
index 98fb04e16..6f1b32b89 100644
--- a/README.md
+++ b/README.md
@@ -34,23 +34,26 @@ The plan is to use OCI projects and best of breed libraries for different aspect
 
 ## Podman Information for Developers
 
-**[Installation notes](/install.md)**
+**[Installation notes](install.md)**
 Information on how to install Podman in your environment.
 
 **[OCI Hooks Support](pkg/hooks/README.md)**
 Information on how Podman configures [OCI Hooks][spec-hooks] to run when launching a container.
 
-**[Podman Commands](/commands.md)**
+**[Podman API](API.md)**
+Documentation on the Podman API using [Varlink](https://www.varlink.org/).
+
+**[Podman Commands](commands.md)**
 A list of the Podman commands with links to their man pages and in many cases videos
 showing the commands in use.
 
-**[Podman Usage Transfer](/transfer.md)**
+**[Podman Troubleshooting Guide](troubleshooting.md)**
+A list of common issues and solutions for Podman.
+
+**[Podman Usage Transfer](transfer.md)**
 Useful information for ops and dev transfer as it relates to infrastructure that utilizes Podman.  This page
 includes tables showing Docker commands and their Podman equivalent commands.
 
-**[Podman API](/API.md)**
-Documentation on the Podman API using [Varlink](https://www.varlink.org/).
-
 **[Tutorials](docs/tutorials)**
 Tutorials on using Podman.
 
diff --git a/troubleshooting.md b/troubleshooting.md
new file mode 100644
index 000000000..25e750e40
--- /dev/null
+++ b/troubleshooting.md
@@ -0,0 +1,56 @@
+![PODMAN logo](logo/podman-logo-source.svg)
+
+# Troubleshooting
+
+## A list of common issues and solutions for Podman
+
+---
+### 1) No such image or Bare keys cannot contain ':'
+
+When doing a `podman pull` or `podman build` command and a "common" image can not be pulled,
+it is likely that the `/etc/containers/registries.conf` file is either not installed or possibly
+misconfigured.
+
+#### Symptom
+```
+sudo podman build -f Dockerfile
+STEP 1: FROM alpine
+error building: error creating build container: no such image "alpine" in registry: image not known
+```
+or
+```
+$ sudo podman pull fedora
+error pulling image "fedora": unable to pull fedora: error getting default registries to try: Near line 9 (last key parsed ''): Bare keys cannot contain ':'.
+```
+
+#### Solution
+
+  * Verify that the `/etc/containers/registries.conf` file exists.  If not, verify that the skopeo-containers package is installed.
+  * Verify that the entries in the `[registries.search]` section of the /etc/containers/registries.conf file are valid and reachable.
+    *  i.e. `registries = ['registry.fedoraproject.org', 'quay.io', 'registry.access.redhat.com']`
+
+---
+### 2) http: server gave HTTP response to HTTPS client
+
+When doing a Podman command such as `build`, `commit`, `pull`, or `push` to a registry,
+tls verification is turned on by default.  If authentication is not used with
+those commands, this error can occur.
+
+#### Symptom
+```
+podman push alpine docker://localhost:5000/myalpine:latest
+Getting image source signatures
+Get https://localhost:5000/v2/: http: server gave HTTP response to HTTPS client
+```
+
+#### Solution
+
+By default tls verification is turned on when communicating to registries from
+Podman.  If the registry does not require authentication the Podman commands
+such as `build`, `commit`, `pull` and `push` will fail unless tls verification is turned
+off using the `--tls-verify` option.  **NOTE:** It is not at all recommended to
+communicate with a registry and not use tls verification.
+
+  * Turn off tls verification by passing false to the tls-verification option.
+  * I.e. `podman push --tls-verify=false alpine docker://localhost:5000/myalpine:latest`
+---