From e9d0e68b97d981c2679c6b8b90c88d586b944acb Mon Sep 17 00:00:00 2001 From: Ying Li Date: Thu, 19 Nov 2015 23:31:27 -0800 Subject: [PATCH] Add information on how to run notary-server from a docker image. Also include information on how to override the configuration file in the docker image. Signed-off-by: Ying Li --- docs/notary-server-config.md | 18 +++++++--- docs/notary-server.md | 69 ++++++++++++++++++++++++++++++------ 2 files changed, 72 insertions(+), 15 deletions(-) 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,