mirrors/nomulus
1
0
Fork 0
mirror of https://github.com/google/nomulus synced 2026-01-03 11:45:39 +00:00
Code Issues Releases Wiki Activity

Reorganize install instructions across multiple help files

Browse Source 
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
This commit is contained in:
mcilwain
2016-10-06 12:34:43 -07:00
committed by Ben McIlwain
parent 940fadff8a
commit 30adfd28fc
5 changed files with 340 additions and 254 deletions
Download Patch File Download Diff File Expand all files Collapse all files

316
docs/install.md
View File

@@ -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
should be coming to App Engine soon).
* [Bazel](http://bazel.io/), which is the build system that Nomulus uses. The
minimum required version is 0.3.1.
* [Google App Engine SDK for Java][app-engine-sdk], especially `appcfg`, which
is a command-line tool that runs locally that is used to communicate with
the App Engine cloud.
* A recent version of the [Java 7 JDK][java-jdk7].
* [Bazel build system](http://bazel.io/) >= version 0.3.1. Make sure to
download the JDK7-compatible version.
* [Google App Engine SDK for Java][app-engine-sdk], and configure aliases to
to the `gcloud` and `appcfg.sh` utilities (you'll use them a lot).
* [Git](https://git-scm.com/) version control system.
**Note:** The prerequisites and steps in this document are only known to work
and have only been tested on Linux. They might work with some alterations on
other operating systems.
**Note:** App Engine does not yet support Java 8. You need to make sure that you
are using Java 7 to compile the project (consult the output of `java -version`).
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
stable releases, but for now, just download `HEAD` of the master branch as
page](https://github.com/google/nomulus). In the future we will release tagged
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
in your build.
proceed. The most important build output files from the build are the
[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
Engine to deploy to, and set up `appcfg` to connect to it.
application](https://cloud.google.com/appengine/docs/java/quickstart) on Google
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
installation can be deployed (see the Configuration guide for that). It's
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:
Now log in using the command-line Google Cloud Platform SDK and set the default
project to be this one that was newly created:
```shell
$ (cd bazel-genfiles/java/google/registry && ls *.ear)
registry_alpha.ear registry.ear registry_sandbox.ear
registry_crash.ear registry_local.ear
$ (cd bazel-genfiles/java/google/registry && ls *.war)
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
$ gcloud auth login
Your browser has been opened to visit:
[ ... snip logging in via browser ... ]
You are now logged in as [user@email.tld].
$ gcloud config set project acme-registry-alpha
```
Note that there is one EAR file per environment (production is the one without
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.
## Deploy the code to App Engine
Then, use `appcfg` to [deploy the WAR
files](https://cloud.google.com/appengine/docs/java/tools/uploadinganapp):
One interesting quirk about the App Engine SDK is that it can't use `ear` files
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
$ /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
$ mkdir /path/to/app-dir/acme-registry-alpha
$ unzip bazel-genfiles/java/google/registry/registry_alpha.ear \
-d /path/to/app-dir/acme-registry-alpha
$ ls /path/to/app-dir/acme-registry-alpha
backend default META-INF tools
```
## Create test entities
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.
Now deploy the code to App Engine.
```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.
$ appcfg.sh -A acme-registry-alpha --enable_jar_splitting \
update /path/to/app-dir/acme-registry-alpha
Reading application configuration data...
Processing module default
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).
* `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.
Note that the `update` command deploys all three services of Nomulus. In the
future, if you've only made changes to a single service, you can save time and
upload just that one using the `-M` flag to specify the service to update.
### 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
TLD. For the purposes of our example we'll name the registrar "Acme".
Configuration is handled by editing code, rebuilding the project, and deploying
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
$ 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
[app-engine-sdk]: https://cloud.google.com/appengine/docs/java/download
[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