Reorganize install instructions across multiple help files

I've also improved the install instructions based on what actually works when
deploying the GitHub-hosted version of the codebase to App Engine using an
external cloud account.

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=135390967

docs/admin-tool.md

@@ -6,27 +6,42 @@ number of things in a running domain registry environment, including creating
 registrars, updating premium and reserved lists, running an EPP command from a
 given XML file, and performing various backend tasks like re-running RDE if the
 most recent export failed. Its code lives inside the tools package
-(`java/google/registry/tools`), and is compiled by building the `nomulus`
+(`java/google/registry/tools`), and is compiled by building the `nomulus` target
-target in the Bazel BUILD file in that package.
+in the Bazel BUILD file in that package.
 
-To build the tool and display its command-line help, execute this command:
+[TOC]
 
-    $ bazel run //java/google/registry/tools:nomulus -- --help
+## Build the tool
 
-For future invocations you should alias the compiled binary in the
+To build the `nomulus` tool, execute the following `bazel build` command inside
-`bazel-genfiles/java/google/registry` directory or add it to your path so that
+any directory of the codebase. You must rebuild the tool any time that you edit
-you can run it more easily. The rest of this guide assumes that it has been
+configuration or make database schema changes.
+
+```shell
+$ bazel build //java/google/registry/tools:nomulus
+```
+
+It's recommended that you alias the compiled binary located at
+`bazel-genfiles/java/google/registry/nomulus` (or add it to your shell path) so
+that you can run it easily. The rest of this guide assumes that it has been
 aliased to `nomulus`.
 
+## Running the tool
+
 The registry tool is always called with a specific environment to run in using
 the -e parameter. This looks like:
 
-    $ nomulus -e production {command name} {command parameters}
+```shell
+$ nomulus -e production {command name} {command parameters}
+```
 
-To see a list of all available commands along with usage information, run
+You can get help about the tool in general, or about a specific subcommand, as
-nomulus without specifying a command name, e.g.:
+follows:
 
-    $ nomulus -e alpha
+```shell
+$ nomulus -e alpha --help # Lists all subcommands
+$ nomulus -e alpha SUBCOMMAND --help # Help for a specific subcommand
+```
 
 Note that the documentation for the commands comes from JCommander, which parses
 metadata contained within the code to yield documentation.

docs/app-engine-architecture.md

@@ -5,8 +5,8 @@ Registry project as it is implemented in App Engine.
 
 ## Services
 
-The Domain Registry contains three [services]
+The Domain Registry contains three
-(https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine),
+[services](https://cloud.google.com/appengine/docs/python/an-overview-of-app-engine),
 which were previously called modules in earlier versions of App Engine. The
 services are: default (also called front-end), backend, and tools. Each service
 runs independently in a lot of ways, including that they can be upgraded
@@ -27,8 +27,8 @@ wild-cards).
 
 ### Default service
 
-The default service is responsible for all registrar-facing [EPP]
+The default service is responsible for all registrar-facing
-(https://en.wikipedia.org/wiki/Extensible_Provisioning_Protocol) command
+[EPP](https://en.wikipedia.org/wiki/Extensible_Provisioning_Protocol) command
 traffic, all user-facing WHOIS and RDAP traffic, and the admin and registrar web
 consoles, and is thus the most important service. If the service has any
 problems and goes down or stops servicing requests in a timely manner, it will
@@ -202,8 +202,8 @@ real to not, is:
     need only ever be one of these.
 *   `SANDBOX` -- A playground environment for external users to test commands in
     without the possibility of affecting production data. This is the
-    environment new registrars go through [OT&E]
+    environment new registrars go through
-    (https://www.icann.org/resources/unthemed-pages/registry-agmt-appc-e-2001-04-26-en)
+    [OT&E](https://www.icann.org/resources/unthemed-pages/registry-agmt-appc-e-2001-04-26-en)
     in. Sandbox is also useful as a final sanity check to push a new prospective
     build to and allow it to "bake" before pushing it to production.
 *   `QA` -- An internal environment used by business users to play with and sign
@@ -283,13 +283,13 @@ cron.xml is:
 
 ## Cloud Datastore
 
-The Domain Registry platform uses [Cloud Datastore]
+The Domain Registry platform uses [Cloud
-(https://cloud.google.com/appengine/docs/java/datastore/) as its primary
+Datastore](https://cloud.google.com/appengine/docs/java/datastore/) as its
-database. Cloud Datastore is a NoSQL document database that provides automatic
+primary database. Cloud Datastore is a NoSQL document database that provides
-horizontal scaling, high performance, and high availability. All information
+automatic horizontal scaling, high performance, and high availability. All
-that is persisted to Cloud Datastore takes the form of Java classes annotated
+information that is persisted to Cloud Datastore takes the form of Java classes
-with `@Entity` that are located in the `model` package. The [Objectify library]
+annotated with `@Entity` that are located in the `model` package. The [Objectify
-(https://cloud.google.com/appengine/docs/java/gettingstarted/using-datastore-objectify)
+library](https://cloud.google.com/appengine/docs/java/gettingstarted/using-datastore-objectify)
 is used to persist instances of these classes in a format that Datastore
 understands.
 
@@ -384,9 +384,9 @@ registry codebase:
 
 ## Cloud Storage buckets
 
-The Domain Registry platform uses [Cloud Storage]
+The Domain Registry platform uses [Cloud
-(https://cloud.google.com/storage/) for bulk storage of large flat files that
+Storage](https://cloud.google.com/storage/) for bulk storage of large flat files
-aren't suitable for Datastore. These files include backups, RDE exports,
+that aren't suitable for Datastore. These files include backups, RDE exports,
 Datastore snapshots (for ingestion into BigQuery), and reports. Each bucket name
 must be unique across all of Google Cloud Storage, so we use the common
 recommended pattern of prefixing all buckets with the name of the App Engine app
@@ -402,8 +402,8 @@ the App Engine app name:
 *   `PROJECT-gcs-logs` -- This bucket is used at Google to store the GCS access
     logs and storage data. This bucket is not required by the Registry system,
     but can provide useful logging information. For instructions on setup, see
-    the [Cloud Storage documentation]
+    the [Cloud Storage
-    (https://cloud.google.com/storage/docs/access-logs).
+    documentation](https://cloud.google.com/storage/docs/access-logs).
 *   `PROJECT-icann-brda` -- This bucket contains the weekly ICANN BRDA files.
     There is no lifecycle expiration; we keep a history of all the files. This
     bucket must exist for the BRDA process to function.
@@ -421,9 +421,7 @@ the App Engine app name:
     bucket named {project}.appspot.com. This bucket must exist. To keep
     temporary files from building up, a 90-day or 180-day lifecycle should be
     applied to the bucket, depending on how long you want to be able to go back
-    and debug MapReduce problems. At 30 GB per day of generate temporary files,
+    and debug MapReduce problems.
-    this bucket may be the largest consumer of storage, so only save what you
-    actually use.
 
 ## Commit logs
 

docs/configuration.md

@@ -5,8 +5,21 @@ working registry system up and running. Broadly speaking, configuration works in
 two ways -- globally, for the entire sytem, and per-TLD. Global configuration is
 managed by editing code and deploying a new version, whereas per-TLD
 configuration is data that lives in Datastore in `Registry` entities, and is
-updated by running `nomulus` commands without having to deploy a new
+updated by running `nomulus` commands without having to deploy a new version.
-version.
+
+[TOC]
+
+## Initial configuration
+
+Here's a checklist of things that need to be configured upon initial
+installation of the project:
+
+*   Create Google Cloud Storage buckets (see the [App Engine architecture
+    guide](./app-engine-architecture.md)).
+*   Modify `ConfigModule.java` and set project-specific settings such as product
+    name (see below).
+*   Copy and edit `ProductionRegistryConfigExample.java` with your
+    project-specific settings (see below).
 
 ## Environments
 
@@ -116,10 +129,10 @@ to provide from `Keyring`, and you can see examples of them in action in
 configuration. They contain any kind of configuration that is specific to a TLD,
 such as the create/renew price of a domain name, the pricing engine
 implementation, the DNS writer implementation, whether escrow exports are
-enabled, the default currency, the reserved label lists, and more. The
+enabled, the default currency, the reserved label lists, and more. The `nomulus
-`nomulus update_tld` command is used to set all of these options. See
+update_tld` command is used to set all of these options. See the [admin tool
-the [admin tool documentation](./admin-tool.md) for more information, as well as
+documentation](./admin-tool.md) for more information, as well as the
-the command-line help for the `update_tld` command. Unlike global configuration
+command-line help for the `update_tld` command. Unlike global configuration
 above, per-TLD configuration options are stored as data in the running system,
 and thus do not require code pushes to update.
 

docs/first-steps-tutorial.md

@@ -0,0 +1,176 @@
+# First steps tutorial
+
+This document covers the first steps of creating some test entities in a newly
+deployed and configured testing environment. It isn't required, but it does help
+gain familiarity with the system. If you have not already done so, you must
+first complete [installation](./install.md) and [initial
+configuration](./configuration.md).
+
+Note: Do not create these entities on a production environment! All commands
+below use the [`nomulus` admin tool](./admin-tool.md) to interact with the
+running registry system. We'll assume that all commands below are running in the
+`alpha` environment; if you named your environment differently, then use that
+everywhere that `alpha` appears.
+
+[TOC]
+
+### Create a TLD
+
+Pick the name of a TLD to create. For the purposes of this example we'll use
+"example", which conveniently happens to be an ICANN reserved string, meaning
+it'll never be created for real on the Internet at large.
+
+```shell
+$ nomulus -e alpha create_tld example --roid_suffix EXAMPLE \
+  --initial_tld_state GENERAL_AVAILABILITY --tld_type TEST
+[ ... snip confirmation prompt ... ]
+Perform this command? (y/N): y
+Updated 1 entities.
+```
+
+*   `-e` is the environment name (`alpha` in this example).
+*   `create_tld` is the subcommand to create a TLD. The TLD name is "example"
+    which happens to be an ICANN reserved string, and therefore "example" can
+    never be created on the Internet at large.
+*   `--initial_tld_state` defines the intital state of the TLD.
+    `GENERAL_AVAILABILITY`, in the case of our example, allows you to
+    immediately create domain names by bypassing the sunrise and landrush domain
+    registration periods.
+*   `--tld_type` is the type of TLD. `TEST` identifies that the TLD is for
+    testing purposes, where `REAL` identifies the TLD is a live TLD.
+*   `roid_suffix` is the suffix that will be used for repository ids of domains
+    on the TLD. This suffix must be all uppercase and a maximum of eight ASCII
+    characters and can be set t the upper-case equivalent of our TLD name (if it
+    is 8 characters or fewer), such as "EXAMPLE." You can also abbreviate the
+    upper-case TLD name down to 8 characters. Refer to the [gTLD Registry
+    Advisory: Correction of non-compliant ROIDs][roids] for further information.
+
+### Create a registrar
+
+Now we need to create a registrar and give it access to operate on the example
+TLD. For the purposes of our example we'll name the registrar "Acme".
+
+```shell
+$ nomulus -e alpha create_registrar acme --name 'ACME Corp' \
+  --registrar_type TEST --password hunter2 \
+  --icann_referral_email blaine@acme.example --street '123 Fake St' \
+  --city 'Fakington' --state MA --zip 12345 --cc US --allowed_tlds example
+[ ... snip confirmation prompt ... ]
+Perform this command? (y/N): y
+Updated 1 entities.
+Skipping registrar groups creation because only production and sandbox
+support it.
+```
+
+Where:
+
+*   `create_registrar` is the subcommand to create a registrar. The argument you
+    provide ("acme") is the registrar id, called the client identifier, that is
+    the primary key used to refer to the registrar both internally and
+    externally.
+*   `--name` indicates the display name of the registrar, in this case `ACME
+    Corp`.
+*   `--registrar_type` is the type of registrar. `TEST` identifies that the
+    registrar is for testing purposes, where `REAL` identifies the registrar is
+    a real live registrar.
+*   `--password` is the password used by the registrar to log in to the domain
+    registry system.
+*   `--icann_referral_email` is the email address associated with the initial
+    creation of the registrar. This address cannot be changed.
+*   `--allowed_tlds` is a comma-delimited list of top level domains where this
+    registrar has access.
+
+### Create a contact
+
+Now we want to create a contact, as a contact is required before a domain can be
+created. Contacts can be used on any number of domains across any number of
+TLDs, and contain the information on who owns or provides technical support for
+a TLD. These details will appear in WHOIS queries.
+
+```shell
+$ nomulus -e alpha create_contact -c acme --id abcd1234 \
+  --name 'John Smith' --street '234 Fake St' --city 'North Fakington' \
+  --state MA --zip 23456 --cc US --email jsmith@e.mail
+[ ... snip EPP response ... ]
+```
+
+Where:
+
+*   `create_contact` is the subcommand to create a contact.
+*   `-c` is used to define the registrar. The `-c` option is used with most
+    `registry_tool` commands to specify the id of the registrar executing the
+    command. Contact, domain, and host creation all work by constructing an EPP
+    message that is sent to the registry, and EPP commands need to run under the
+    context of a registrar. The "acme" registrar that was created above is used
+    for this purpose.
+*   `--id` is the contact id, and is referenced elsewhere in the system (e.g.
+    when a domain is created and the admin contact is specified).
+*   `--name` is the display name of the contact, which is usually the name of a
+    company or of a person.
+
+The address and `email` fields are required to create a contact.
+
+### Create a host
+
+Hosts are used to specify the IP addresses (either v4 or v6) that are associated
+with a given nameserver. Note that hosts may either be in-bailiwick (on a TLD
+that this registry runs) or out-of-bailiwick. In-bailiwick hosts may
+additionally be subordinate (a subdomain of a domain name that is on this
+registry). Let's create an out-of-bailiwick nameserver, which is the simplest
+type.
+
+```shell
+$ nomulus -e alpha create_host -c acme --host ns1.google.com
+[ ... snip EPP response ... ]
+```
+
+Where:
+
+*   `create_host` is the subcommand to create a host.
+*   `--host` is the name of the host.
+*   `--addresses` (not used here) is the comma-delimited list of IP addresses
+    for the host in IPv4 or IPv6 format, if applicable.
+
+Note that hosts are required to have IP addresses if they are subordinate, and
+must not have IP addresses if they are not subordinate.
+
+### Create a domain
+
+To tie it all together, let's create a domain name that uses the above contact
+and host.
+
+```shell
+$ nomulus -e alpha create_domain -c acme --domain fake.example \
+  --admin abcd1234 --tech abcd1234 --registrant abcd1234 \
+  --nameservers ns1.google.com
+[ ... snip EPP response ... ]
+```
+
+Where:
+
+*   `create_domain` is the subcommand to create a domain name.
+*   `-c` is used to define the registrar.
+*   `--domain` is used to identify the domain name to be created.
+*   `--admin` is the administrative contact's id.
+*   `--tech` is the technical contact's id.
+*   `--registrant` is the registrant contact's id.
+*   `--nameservers` identifies the host.
+
+Note how the same contact id is used for the administrative, technical, and
+registrant contact. It is common for domain names to use the same details for
+all contacts on a domain name.
+
+### Verify test entities using WHOIS
+
+To verify that everything worked, let's query the WHOIS information for
+fake.example:
+
+```shell
+$ nomulus -e alpha whois_query fake.example
+[ ... snip WHOIS response ... ]
+```
+
+You should see all of the information in WHOIS that you entered above for the
+contact, nameserver, and domain.
+
+[roids]: https://www.icann.org/resources/pages/correction-non-compliant-roids-2015-08-26-en

docs/install.md

@@ -8,24 +8,23 @@ This document covers the steps necessary to download, build, and deploy Nomulus.
 
 You will need the following programs installed on your local machine:
 
-*   A recent version of the [Java 7 JDK][java-jdk7] (note that Java 8 support
+*   A recent version of the [Java 7 JDK][java-jdk7].
-    should be coming to App Engine soon).
+*   [Bazel build system](http://bazel.io/) >= version 0.3.1. Make sure to
-*   [Bazel](http://bazel.io/), which is the build system that Nomulus uses. The
+    download the JDK7-compatible version.
-    minimum required version is 0.3.1.
+*   [Google App Engine SDK for Java][app-engine-sdk], and configure aliases to
-*   [Google App Engine SDK for Java][app-engine-sdk], especially `appcfg`, which
+    to the `gcloud` and `appcfg.sh` utilities (you'll use them a lot).
-    is a command-line tool that runs locally that is used to communicate with
-    the App Engine cloud.
 *   [Git](https://git-scm.com/) version control system.
 
-**Note:** The prerequisites and steps in this document are only known to work
+**Note:** App Engine does not yet support Java 8. You need to make sure that you
-and have only been tested on Linux. They might work with some alterations on
+are using Java 7 to compile the project (consult the output of `java -version`).
-other operating systems.
+Also, the instructions in this document have only been tested on Linux. They
+might work with some alterations on other operating systems.
 
-## Download the code
+## Download the codebase
 
 Start off by using git to download the latest version from the [Nomulus GitHub
-page](https://github.com/google/nomulus). In the future we may support more
+page](https://github.com/google/nomulus). In the future we will release tagged
-stable releases, but for now, just download `HEAD` of the master branch as
+stable versions, but for now, just download `HEAD` of the master branch as
 follows:
 
 ```shell
@@ -50,7 +49,7 @@ The most important directories are:
 Everything else, especially `third_party`, contains dependencies that are used
 by the project.
 
-## Build the project and run tests
+## Build the codebase
 
 The first step is to build the project, and verify that this completes
 successfully. This will also download and install dependencies.
@@ -63,8 +62,27 @@ INFO: Elapsed time: 124.433s, Critical Path: 116.92s
 ```
 
 There may be some warnings thrown, but if there are no errors, then you can
-proceed. Next, run the tests to verify that all expected functionality succeeds
+proceed. The most important build output files from the build are the
-in your build.
+[ear](https://en.wikipedia.org/wiki/EAR_\(file_format\)) files:
+
+```shell
+$ ls bazel-genfiles/java/google/registry/*.ear
+registry_alpha.ear  registry.ear        registry_sandbox.ear
+registry_crash.ear  registry_local.ear
+```
+
+Each `ear` file is a compiled version codebase ready to deploy to App Engine for
+a specific environment. By default there are five environments, with the unnamed
+one being production. Each `ear` file contains App Engine-specific metadata
+files in the `META-INF` directory, as well as three directories for the three
+services used in the project, `default`, `backend`, and `tools` (each of these
+directories is an unpacked
+[war](https://en.wikipedia.org/wiki/WAR_\(file_format\)) file.
+
+## (Optional) Run the tests
+
+You can run the tests to verify that all expected functionality succeeds in your
+build:
 
 ```shell
 $ nice bazel --batch test //javatests/google/registry/... \
@@ -78,223 +96,89 @@ slowing down your computer too badly. Refer to the [Bazel User
 Manual](https://www.bazel.io/versions/master/docs/bazel-user-manual.html) for
 more information.
 
-## Deploy the code to App Engine
+## Create an App Engine project
 
 First, [create an
-application](https://cloud.google.com/appengine/docs/java/quickstart) on App
+application](https://cloud.google.com/appengine/docs/java/quickstart) on Google
-Engine to deploy to, and set up `appcfg` to connect to it.
+Cloud Platform. Make sure to choose a good Project ID, as it will be used
+repeatedly in a large number of places. If your company is named Acme, then a
+good Project ID for your production environment would be "acme-registry". Keep
+in mind that project IDs for non-production environments should be suffixed with
+the name of the environment (see the [App Engine architecture
+guide](./app-engine-architecture.md) for more details). For the purposes of this
+example we'll deploy to the "alpha" environment, which is used for developer
+testing. The Project ID will thus be `acme-registry-alpha`.
 
-You are going to need to configure a variety of things before a working
+Now log in using the command-line Google Cloud Platform SDK and set the default
-installation can be deployed (see the Configuration guide for that). It's
+project to be this one that was newly created:
-recommended to at least confirm that the default version of the code can be
-pushed at all first before diving into that, with the expectation that things
-won't work properly until they are configured.
-
-All of the [EAR](https://en.wikipedia.org/wiki/EAR_\(file_format\)) and
-[WAR](https://en.wikipedia.org/wiki/WAR_\(file_format\)) files for the different
-environments, which were built in the previous step, are outputted to the
-`bazel-genfiles` directory as follows:
 
 ```shell
-$ (cd bazel-genfiles/java/google/registry && ls *.ear)
+$ gcloud auth login
-registry_alpha.ear  registry.ear        registry_sandbox.ear
+Your browser has been opened to visit:
-registry_crash.ear  registry_local.ear
+[ ... snip logging in via browser ... ]
-
+You are now logged in as [user@email.tld].
-$ (cd bazel-genfiles/java/google/registry && ls *.war)
+$ gcloud config set project acme-registry-alpha
-mandatory_stuff.war           registry_default_local.war
-registry_backend_alpha.war    registry_default_sandbox.war
-registry_backend_crash.war    registry_default.war
-registry_backend_local.war    registry_tools_alpha.war
-registry_backend_sandbox.war  registry_tools_crash.war
-registry_backend.war          registry_tools_local.war
-registry_default_alpha.war    registry_tools_sandbox.war
-registry_default_crash.war    registry_tools.war
 ```
 
-Note that there is one EAR file per environment (production is the one without
+## Deploy the code to App Engine
-an environment in the file name), whereas there is one WAR file per service per
-environment, with there being three services in total: default, backend, and
-tools.
 
-Then, use `appcfg` to [deploy the WAR
+One interesting quirk about the App Engine SDK is that it can't use `ear` files
-files](https://cloud.google.com/appengine/docs/java/tools/uploadinganapp):
+in their packed form; you have to unpack them first, then run `appcfg.sh`
+commands on the unpacked contents of the `ear`. So grab the compiled `ear` file
+for the alpha environment (it's one of the outputs of the build step earlier),
+copy it to another directory, and extract it:
 
 ```shell
-$ cd /path/to/downloaded/appengine/app
+$ mkdir /path/to/app-dir/acme-registry-alpha
-$ /path/to/appcfg.sh update /path/to/registry_default.war
+$ unzip bazel-genfiles/java/google/registry/registry_alpha.ear \
-$ /path/to/appcfg.sh update /path/to/registry_backend.war
+  -d /path/to/app-dir/acme-registry-alpha
-$ /path/to/appcfg.sh update /path/to/registry_tools.war
+$ ls /path/to/app-dir/acme-registry-alpha
+backend  default  META-INF  tools
 ```
 
-## Create test entities
+Now deploy the code to App Engine.
-
-Once the code is deployed, an optional next step is to play around with creating
-some fake entities in the registry, including a TLD, a registrar, a domain, a
-contact, and a host. Note: Do this on a non-production environment! All commands
-below use `nomulus` to interact with the running registry system; see the
-documentation on `nomulus` for additional information on it. We'll assume that
-all commands below are running in the `alpha` environment; if you named your
-environment differently, then use that everywhere that `alpha` appears.
-
-### Create a TLD
-
-Pick the name of a TLD to create. For the purposes of this example we'll use
-"example", which conveniently happens to be an ICANN reserved string, meaning
-it'll never be created for real on the Internet at large.
 
 ```shell
-$ nomulus -e alpha create_tld example --roid_suffix EXAMPLE \
+$ appcfg.sh -A acme-registry-alpha --enable_jar_splitting \
-  --initial_tld_state GENERAL_AVAILABILITY --tld_type TEST
+  update /path/to/app-dir/acme-registry-alpha
-[ ... snip confirmation prompt ... ]
+Reading application configuration data...
-Perform this command? (y/N): y
+Processing module default
-Updated 1 entities.
+Oct 05, 2016 12:16:59 PM com.google.apphosting.utils.config.IndexesXmlReader readConfigXml
+INFO: Successfully processed /usr/local/google/home/mcilwain/Code/acme-registry-alpha/./default/WEB-INF/datastore-indexes.xml
+Ignoring application.xml context-root element, for details see https://developers.google.com/appengine/docs/java/modules/#config
+Processing module backend
+Ignoring application.xml context-root element, for details see https://developers.google.com/appengine/docs/java/modules/#config
+Processing module tools
+Ignoring application.xml context-root element, for details see https://developers.google.com/appengine/docs/java/modules/#config
+
+Beginning interaction for module default...
+0% Created staging directory at: '/tmp/appcfg7185922945263751117.tmp'
+5% Scanning for jsp files.
+20% Scanning files on local disk.
+[ ... snip ... ]
+Beginning interaction for module backend...
+[ ... snip ... ]
+Beginning interaction for module tools...
+[ ... snip ... ]
 ```
 
-*   `-e` is the environment name (`alpha` in this example).
+Note that the `update` command deploys all three services of Nomulus. In the
-*   `create_tld` is the subcommand to create a TLD. The TLD name is "example"
+future, if you've only made changes to a single service, you can save time and
-    which happens to be an ICANN reserved string, and therefore "example" can
+upload just that one using the `-M` flag to specify the service to update.
-    never be created on the Internet at large.
-*   `--initial_tld_state` defines the intital state of the TLD.
-    `GENERAL_AVAILABILITY`, in the case of our example, allows you to
-    immediately create domain names by bypassing the sunrise and landrush domain
-    registration periods.
-*   `--tld_type` is the type of TLD. `TEST` identifies that the TLD is for
-    testing purposes, where `REAL` identifies the TLD is a live TLD.
-*   `roid_suffix` is the suffix that will be used for repository ids of domains
-    on the TLD. This suffix must be all uppercase and a maximum of eight ASCII
-    characters and can be set t the upper-case equivalent of our TLD name (if it
-    is 8 characters or fewer), such as "EXAMPLE." You can also abbreviate the
-    upper-case TLD name down to 8 characters. Refer to the [gTLD Registry
-    Advisory: Correction of non-compliant ROIDs][roids] for further information.
 
-### Create a registrar
+To verify successful deployment, visit
+https://acme-registry-alpha.appspot.com/registrar in your browser (adjusting
+approrpriately for the project ID that you actually used). If the project
+deployed successfully, you'll see a "You need permission" page indicating that
+you need to configure the system and grant access to your Google account. It's
+time to go to the next step, configuration.
 
-Now we need to create a registrar and give it access to operate on the example
+Configuration is handled by editing code, rebuilding the project, and deploying
-TLD. For the purposes of our example we'll name the registrar "Acme".
+again. See the [configuration guide](./configuration.md) for more details. Once
+you have completed basic configuration (including most critically the project ID
+in your copy of `ProductionRegistryConfigExample`), you can rebuild and start
+using `registry_tool` to create test entities in your newly deployed system. See
+the [first steps tutorial](./first-steps-tutorial.md) for more information.
 
-```shell
+[app-engine-sdk]: https://cloud.google.com/appengine/docs/java/download
-$ nomulus -e alpha create_registrar acme --name 'ACME Corp' \
-  --registrar_type TEST --password hunter2 \
-  --icann_referral_email blaine@acme.example --street '123 Fake St' \
-  --city 'Fakington' --state MA --zip 12345 --cc US --allowed_tlds example
-[ ... snip confirmation prompt ... ]
-Perform this command? (y/N): y
-Updated 1 entities.
-Skipping registrar groups creation because only production and sandbox
-support it.
-```
-
-Where:
-
-*   `create_registrar` is the subcommand to create a registrar. The argument you
-    provide ("acme") is the registrar id, called the client identifier, that is
-    the primary key used to refer to the registrar both internally and
-    externally.
-*   `--name` indicates the display name of the registrar, in this case `ACME
-    Corp`.
-*   `--registrar_type` is the type of registrar. `TEST` identifies that the
-    registrar is for testing purposes, where `REAL` identifies the registrar is
-    a real live registrar.
-*   `--password` is the password used by the registrar to log in to the domain
-    registry system.
-*   `--icann_referral_email` is the email address associated with the initial
-    creation of the registrar. This address cannot be changed.
-*   `--allowed_tlds` is a comma-delimited list of top level domains where this
-    registrar has access.
-
-### Create a contact
-
-Now we want to create a contact, as a contact is required before a domain can be
-created. Contacts can be used on any number of domains across any number of
-TLDs, and contain the information on who owns or provides technical support for
-a TLD. These details will appear in WHOIS queries.
-
-```shell
-$ nomulus -e alpha create_contact -c acme --id abcd1234 \
-  --name 'John Smith' --street '234 Fake St' --city 'North Fakington' \
-  --state MA --zip 23456 --cc US --email jsmith@e.mail
-[ ... snip EPP response ... ]
-```
-
-Where:
-
-*   `create_contact` is the subcommand to create a contact.
-*   `-c` is used to define the registrar. The `-c` option is used with most
-    `registry_tool` commands to specify the id of the registrar executing the
-    command. Contact, domain, and host creation all work by constructing an EPP
-    message that is sent to the registry, and EPP commands need to run under the
-    context of a registrar. The "acme" registrar that was created above is used
-    for this purpose.
-*   `--id` is the contact id, and is referenced elsewhere in the system (e.g.
-    when a domain is created and the admin contact is specified).
-*   `--name` is the display name of the contact, which is usually the name of a
-    company or of a person.
-
-The address and `email` fields are required to create a contact.
-
-### Create a host
-
-Hosts are used to specify the IP addresses (either v4 or v6) that are associated
-with a given nameserver. Note that hosts may either be in-bailiwick (on a TLD
-that this registry runs) or out-of-bailiwick. In-bailiwick hosts may
-additionally be subordinate (a subdomain of a domain name that is on this
-registry). Let's create an out-of-bailiwick nameserver, which is the simplest
-type.
-
-```shell
-$ nomulus -e alpha create_host -c acme --host ns1.google.com
-[ ... snip EPP response ... ]
-```
-
-Where:
-
-*   `create_host` is the subcommand to create a host.
-*   `--host` is the name of the host.
-*   `--addresses` (not used here) is the comma-delimited list of IP addresses
-    for the host in IPv4 or IPv6 format, if applicable.
-
-Note that hosts are required to have IP addresses if they are subordinate, and
-must not have IP addresses if they are not subordinate.
-
-### Create a domain
-
-To tie it all together, let's create a domain name that uses the above contact
-and host.
-
-```shell
-$ nomulus -e alpha create_domain -c acme --domain fake.example \
-  --admin abcd1234 --tech abcd1234 --registrant abcd1234 \
-  --nameservers ns1.google.com
-[ ... snip EPP response ... ]
-```
-
-Where:
-
-*   `create_domain` is the subcommand to create a domain name.
-*   `-c` is used to define the registrar.
-*   `--domain` is used to identify the domain name to be created.
-*   `--admin` is the administrative contact's id.
-*   `--tech` is the technical contact's id.
-*   `--registrant` is the registrant contact's id.
-*   `--nameservers` identifies the host.
-
-Note how the same contact id is used for the administrative, technical, and
-registrant contact. It is common for domain names to use the same details for
-all contacts on a domain name.
-
-### Verify test entities using WHOIS
-
-To verify that everything worked, let's query the WHOIS information for
-fake.example:
-
-```shell
-$ nomulus -e alpha whois_query fake.example
-[ ... snip WHOIS response ... ]
-```
-
-You should see all of the information in WHOIS that you entered above for the
-contact, nameserver, and domain.
-
-[app-engine-sdk]: https://cloud.google.com/appengine/downloads#Google_App_Engine_SDK_for_Java
 [java-jdk7]: http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html
-[roids]: https://www.icann.org/resources/pages/correction-non-compliant-roids-2015-08-26-en