diff --git a/examples/postgres/README.md b/examples/postgres/README.md
index 5ea1c441..f452d8ef 100644
--- a/examples/postgres/README.md
+++ b/examples/postgres/README.md
@@ -1,9 +1,41 @@
 ## Postgres Dockerfile
-This example shows a Dockerfile that can be used to connect Jupyterhub to a Postgres backend.
 
-### Running the Container
-0. Replace `ENV JPY_PSQL_PASSWORD arglebargle` with your own password in the Dockerfile.
+This example shows how you can connect Jupyterhub to a Postgres database
+instead of the default SQLite backend.
+
+### Running Postgres with Jupyterhub on the host.
+0. Replace `ENV JPY_PSQL_PASSWORD arglebargle` with your own password in the
+   Dockerfile for `examples/postgres/db`. (Alternatively you can pass -e
+   `JPY_PSQL_PASSWORD=<password>` when you start the db container.)
+
 1. `cd` to the root of your jupyterhub repo.
-2. Build the postgres image with `docker build -t jupyterhub-postgres examples/postgres_db/`.  This may take some time the first time it's run.
-3. Run the image with `docker run -d -p 5433:5432 jupyterhub-postgres`.  This will start a postgres daemon container in the background that's listening on your localhost port 5433.
-4. Run jupyterhub with `jupyterhub--db=postgresql://jupyterhub:<password>@localhost:5433/jupyterhub`.
+
+2. Build the postgres image with `docker build -t jupyterhub-postgres-db
+   examples/postgres/db`.  This may take a minute or two the first time it's
+   run.
+
+3. Run the db image with `docker run -d -p 5433:5432 jupyterhub-postgres`.
+   This will start a postgres daemon container in the background that's
+   listening on your localhost port 5433.
+
+4. Run jupyterhub with
+   `jupyterhub--db=postgresql://jupyterhub:<password>@localhost:5433/jupyterhub`.
+
+### Running Postgres with Containerized Jupyterhub.
+0. Replace `ENV JPY_PSQL_PASSWORD arglebargle` with your own password in the
+   Dockerfile for `examples/postgres/hub`. (Alternatively you can pass -e
+   `JPY_PSQL_PASSWORD=<password>` when you start the hub container.)
+
+1. Do steps 0-2 in from the above section, ensuring that the values set/passed
+   for `JPY_PSQL_PASSWORD` match for the hub and db containers.
+
+2. Build the hub image with `docker build -t jupyterhub-postgres-db
+   examples/postgres/db`.  This may take a minute or two the first time it's run.
+
+3. Run the db image with `docker run -d --name=jpy-db
+   jupyterhub-postgres`. Note that, unlike when connecting to a host machine
+   jupyterhub, we don't specify a port-forwarding scheme here, but we do need
+   to specify a name for the container.
+
+4. Run the containerized hub with `docker run -it --link jpy-db:postgres
+   jupyterhub-postgres-hub`.
diff --git a/examples/postgres/hub/Dockerfile b/examples/postgres/hub/Dockerfile
index f8fe284e..a9e02892 100644
--- a/examples/postgres/hub/Dockerfile
+++ b/examples/postgres/hub/Dockerfile
@@ -5,5 +5,5 @@ RUN apt-get install -y libpq-dev \
     && apt-get clean -y \
     && pip3 install psycopg2
 
-# Replace this with your own password
+# Replace this with your own password.
 ENV JPY_PSQL_PASSWORD arglebargle