Add documentation on creating sample EPP resource in system setup

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

docs/install.md

@@ -120,3 +120,128 @@ Then, use `appcfg` to [deploy the WAR files](https://cloud.google.com/appengine/
     $ /path/to/appcfg.sh update /path/to/registry_default.war
     $ /path/to/appcfg.sh update /path/to/registry_backend.war
     $ /path/to/appcfg.sh update /path/to/registry_tools.war
+
+## Creating test entities
+
+Once the code is deployed, the next step is to play around with creating some
+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
+`registry_tool` to interact with the running registry system; see the
+documentation on `registry_tool` 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.
+
+    $ registry_tool -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.
+
+The name of the TLD is the main parameter passed to the command.  The initial
+TLD state is set here to general availability, bypassing sunrise and landrush,
+so that domain names can be created immediately in the following steps.  The TLD
+type is set to `TEST` (the other alternative being `REAL`) for obvious reasons.
+
+`roid_suffix` is the suffix that will be used for repository ids of domains on
+the TLD -- it must be all uppercase and a maximum of eight ASCII characters.
+ICANN
+[recommends](https://www.icann.org/resources/pages/correction-non-compliant-roids-2015-08-26-en)
+a unique ROID suffix per TLD.  The easiest way to come up with one is to simply
+use the entire uppercased TLD string if it is eight characters or fewer, or
+abbreviate it in some sensible way down to eight if it is longer.  The full repo
+id of a domain resource is a hex string followed by the suffix,
+e.g. `12F7CDF3-EXAMPLE` for our example TLD.
+
+### 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".
+
+    $ registry_tool -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.
+
+In the command above, "acme" is the internal registrar id that is the primary
+key used to refer to the registrar.  The `name` is the display name that is used
+less often, primarily in user interfaces.  We again set the type of the resource
+here to `TEST`.  The `password` is the EPP password that the registrar uses to
+log in with.  The `icann_referral_email` is the email address associated with
+the initial creation of the registrar -- note that the registrar cannot change
+it later.  The address fields are self-explanatory (note that other parameters
+are available for international addresses).  The `allowed_tlds` parameter is a
+comma-delimited list of TLDs that the registrar has access to, and here is set
+to the example TLD.
+
+### 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.  Note the `-c` parameter,
+which stands for client identifier: This is used on most `registry_tool`
+commands, and is used to specify the id of the registrar that the command will
+be executed using.  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.
+
+    $ registry_tool -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 ... ]
+
+The `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).  The `name` is the
+display name of the contact, which is usually the name of a company or of a
+person.  Again, the address fields are required, along with an `email`.
+
+### 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.
+
+    $ my_registry_tool -e alpha create_host -c acme --host ns1.google.com
+    [ ... snip EPP response ... ]
+
+Note that hosts are required to have IP addresses if they are subordinate, and
+must not have IP addresses if they are not subordinate.  Use the `--addresses`
+parameter to set the IP addresses on a host, passing in a comma-delimited list
+of IP addresses in either IPv4 or IPv6 format.
+
+### Create a domain
+
+To tie it all together, let's create a domain name that uses the above contact
+and host.
+
+    $ registry_tool -e alpha create_domain -c acme --domain fake.example \
+      --admin abcd1234 --tech abcd1234 --registrant abcd1234 \
+      --nameservers ns1.google.com
+    [ ... snip EPP response ... ]
+
+Note how the same contact id (from above) is used for the administrative,
+technical, and registrant contact.  This is quite common on domain names.
+
+To verify that everything worked, let's query the WHOIS information for
+fake.example:
+
+    $ registry_tool -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.