diff --git a/docs/notary-server-config.md b/docs/notary-server-config.md
index c2f0052107..affdeeccef 100644
--- a/docs/notary-server-config.md
+++ b/docs/notary-server-config.md
@@ -89,14 +89,18 @@ Example:
no |
Specifies the private key to use for HTTPS. Must be
provided together with tls_cert_file , or not at all.
- If neither are provided, the server will use HTTP instead of HTTPS. |
+ If neither are provided, the server will use HTTP instead of HTTPS.
+ The path is relative to the current working directory where
+ notary-server is run.
tls_cert_file |
no |
Specifies the certificate to use for HTTPS. Must be
provided together with tls_key_file , or not at all.
- If neither are provided, the server will use HTTP instead of HTTPS. |
+ If neither are provided, the server will use HTTP instead of HTTPS.
+ The path is relative to the current working directory where
+ notary-server is run.
@@ -207,21 +211,25 @@ are needed configure it.
tls_ca_file |
no |
The root CA or TLS cert of the remote service, if it is
- self-signed or otherwise not in the system's default trust roots |
+ self-signed or otherwise not in the system's default trust roots.
+ The path is relative to the current working directory where
+ notary-server is run.
tls_client_key |
no |
The private key to use for TLS mutual authentication.
Must be provided together with tls_client_cert or not
- at all. |
+ at all. The path is relative to the current working directory where
+ notary-server is run.
tls_client_cert |
optional |
The certificate to use for TLS mutual authentication.
Must be provided together with tls_client_key or not
- at all. |
+ at all. The path is relative to the current working directory where
+ notary-server is run.
diff --git a/docs/notary-server.md b/docs/notary-server.md
index 75aa82d589..49ba7ab0b5 100644
--- a/docs/notary-server.md
+++ b/docs/notary-server.md
@@ -14,7 +14,7 @@ The notary server is a remote store for, and coordinates updates to, the signed
metadata files for a repository (which are created by clients). The server is
also responsible for creating and keeping track of timestamp keys for each repo,
and signing a timestamp file for each repo whenever a client sends updates,
-after verifying the root/target/snapshot signatures on the client update.
+after verifying the root, target, and snapshot signatures on the client update.
### Authentication
@@ -54,18 +54,67 @@ compromised can sign any number of other client certs.
As an example, please see [this script](opensslGenCert.sh) to see how to
generate client SSL certs with basic constraints using OpenSSL.
-### How to configure notary server
+### How to configure and run notary server
-A JSON configuration file needs to be passed as a parameter/flag when starting
-up Notary Server:
-
-```
-notary-server -config /path/to/configuration.json
-```
-
-Please see the [Notary Server configuration document](notary-server-config.md)
+A JSON configuration file is used to configure Notary Server. Please see the
+[Notary Server configuration document](notary-server-config.md)
for more details about the format of the configuration file.
+The parameters of the configuration file can also be overwritten using
+environment variables of the form `NOTARY_SERVER_var`, where `var` is the
+full path from the top level of the configuration file to the variable you want
+to override, in all caps. A change in level is denoted with a `_`.
+
+For instance, one part of the configuration file might look like:
+
+```json
+"storage": {
+ "backend": "mysql",
+ "db_url": "dockercondemo:dockercondemo@tcp(notary-mysql)/dockercondemo"
+}
+```
+
+If you would like to specify a different `db_url`, the full path from the top
+of the configuration tree is `storage -> db_url`, so the environment variable
+to set would be `NOTARY_SERVER_STORAGE_DB_URL`.
+
+Note that you cannot override an intermediate level name. Setting
+`NOTARY_SERVER_STORAGE=""` will not disable the MySQL storage. Each leaf
+parameter value must be set indepedently.
+
+#### Running a Docker image
+
+Get the official Docker image, which comes with some sane defaults. You can
+run it with your own signer service and mysql DB, or in the example below, with
+just a local signing service and memory store:
+
+```
+$ docker pull docker.io/docker/notary-server
+$ docker run -p "4443:4443" \
+ -e NOTARY_SERVER_TRUST_SERVICE_TYPE=local \
+ -e NOTARY_SERVER_STORAGE_BACKEND=""
+ -e NOTARY_SERVER_STORAGE_DB_URL=""
+ notary-server
+```
+
+Alternately, you can run with your own configuration file entirely. The
+docker image loads the config file from `/opt/notary-server/config.json`, so
+you can mount your config file at `/opt/notary-server`:
+
+```
+$ docker run -p "4443:4443" -v /path/to/your/config/dir:/opt/notary-server
+```
+
+#### Running the binary
+A JSON configuration file needs to be passed as a parameter/flag when starting
+up the Notary Server binary. Environment variables can also be set in addition
+to the configuration file, but the configuration file is required.
+
+```
+$ export NOTARY_SERVER_STORAGE_DB_URL=myuser:mypass@tcp(my-db)/dbname
+$ NOTARY_SERVER_LOGGING_LEVEL=info notary-server -config /path/to/config.json
+```
+
### What happens if the server is compromised
The server does not hold any keys for the repository except the timestamp key,