mirror of
https://github.com/google/nomulus.git
synced 2025-08-04 00:42:12 +02:00
Update user-facing documentation (#662)
* Update user-facing documentation Give our docs a complete overhaul to account for changes in the system, notably the requirement to configure postgresql. * Fix dangling sentence. * Merge branch 'master' into admin-docs
This commit is contained in:
Michael Muller
GitHub
parent
a302cf3e04
commit
b44c7d2786
3 changed files with 274 additions and 135 deletions
145
docs/install.md
145
docs/install.md
|
|
@ -6,6 +6,7 @@ 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 11 JDK][java-jdk11].
|
||||
* [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).
|
||||
|
|
@ -18,9 +19,9 @@ on other operating systems.
|
|||
## 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 will release tagged
|
||||
stable versions, but for now, just download `HEAD` of the master branch as
|
||||
follows:
|
||||
page](https://github.com/google/nomulus). You may checkout any of the daily
|
||||
tagged versions (e.g. `nomulus-20200629-RC00`), but in general it is also
|
||||
safe to simply checkout from HEAD:
|
||||
|
||||
```shell
|
||||
$ git clone git@github.com:google/nomulus.git
|
||||
|
|
@ -33,16 +34,20 @@ AUTHORS docs javascript python third_party
|
|||
CONTRIBUTING.md google javatests README.md WORKSPACE
|
||||
```
|
||||
|
||||
The most important directories are:
|
||||
Most of the directory tree is organized into gradle sub-projects (see
|
||||
`settings.gradle` for details). The following other top-level directories are
|
||||
also defined:
|
||||
|
||||
* `docs` -- the documentation (including this install guide)
|
||||
* `java/google/registry` -- all of the source code of the main project
|
||||
* `javatests/google/registry` -- all of the tests for the project
|
||||
* `buildSrc` -- Gradle extensions specific to our local build and release
|
||||
methodology.
|
||||
* `config` -- Tools for build and code hygiene.
|
||||
* `docs` -- The documentation (including this install guide)
|
||||
* `gradle` -- Configuration and code managed by the gradle build system.
|
||||
* `java-format` -- The Google java formatter and wrapper scripts to use it
|
||||
incrementally.
|
||||
* `python` -- Some Python reporting scripts
|
||||
* `scripts` -- Scripts for configuring development environments
|
||||
|
||||
Everything else, especially `third_party`, contains dependencies that are used
|
||||
by the project.
|
||||
* `release` -- Configuration for our continuous integration process.
|
||||
* `third_party` -- External dependencies.
|
||||
|
||||
## Build the codebase
|
||||
|
||||
|
|
@ -50,48 +55,21 @@ The first step is to build the project, and verify that this completes
|
|||
successfully. This will also download and install dependencies.
|
||||
|
||||
```shell
|
||||
$ bazel --batch build --javacopt="-target 8 -source 8" \
|
||||
//java{,tests}/google/registry/...
|
||||
INFO: Found 584 targets...
|
||||
$ ./nom_build build
|
||||
Starting a Gradle Daemon (subsequent builds will be faster)
|
||||
Plugins: Using default repo...
|
||||
|
||||
> Configure project :buildSrc
|
||||
Java dependencies: Using Maven central...
|
||||
[ .. snip .. ]
|
||||
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. The most important build output files from the build are the
|
||||
[ear](https://en.wikipedia.org/wiki/EAR_\(file_format\)) files:
|
||||
The `nom_build` script is just a wrapper around `gradlew`. Its main
|
||||
additional value is that it formalizes the various properties used in the
|
||||
build as command-line flags.
|
||||
|
||||
```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 --javacopt="-target 8 -source 8" \
|
||||
//javatests/google/registry/... \
|
||||
--local_ram_resources=1000 --local_cpu_resources=3
|
||||
Executed 360 out of 360 tests: 360 tests pass.
|
||||
```
|
||||
|
||||
**Note:** The tests can be pretty resource intensive, so experiment with
|
||||
different values of parameters to optimize between low running time and not
|
||||
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.
|
||||
The "build" command builds all of the code and runs all of the tests. This
|
||||
will take a while.
|
||||
|
||||
## Create an App Engine project
|
||||
|
||||
|
|
@ -117,51 +95,25 @@ You are now logged in as [user@email.tld].
|
|||
$ gcloud config set project acme-registry-alpha
|
||||
```
|
||||
|
||||
Now modify `projects.gradle` with the name of your new project:
|
||||
|
||||
<pre>
|
||||
// The projects to run your deployment Nomulus application.
|
||||
rootProject.ext.projects = ['production': 'your-production-project',
|
||||
'sandbox' : 'your-sandbox-project',
|
||||
'alpha' : <strong>'acme-registry-alpha',</strong>
|
||||
'crash' : 'your-crash-project']
|
||||
</pre>
|
||||
|
||||
Next follow the steps in [configuration](./configuration.md) to configure the
|
||||
complete system or, alternately, read on for an initial deploy in which case
|
||||
you'll need to deploy again after configuration.
|
||||
|
||||
## Deploy the code to App Engine
|
||||
|
||||
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:
|
||||
AppEngine deployment with gradle is straightforward:
|
||||
|
||||
```shell
|
||||
$ 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
|
||||
```
|
||||
|
||||
Now deploy the code to App Engine. We must provide a version string, e.g., live.
|
||||
|
||||
```shell
|
||||
$ appcfg.sh -A acme-registry-alpha --enable_jar_splitting \
|
||||
-V live 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 ... ]
|
||||
```
|
||||
|
||||
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.
|
||||
$ ./nom_build appengineDeploy --environment=alpha
|
||||
|
||||
To verify successful deployment, visit
|
||||
https://acme-registry-alpha.appspot.com/registrar in your browser (adjusting
|
||||
|
|
@ -171,11 +123,12 @@ you need to configure the system and grant access to your Google account. It's
|
|||
time to go to the next step, configuration.
|
||||
|
||||
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 the `nomulus` tool to create test entities in your newly deployed system.
|
||||
See the [first steps tutorial](./first-steps-tutorial.md) for more information.
|
||||
again. See the [configuration guide](./configuration.md) for more details.
|
||||
Once you have completed basic configuration (including most critically the
|
||||
project ID, client id and secret in your copy of the `nomulus-config-*.yaml`
|
||||
files), you can rebuild and start using the `nomulus` tool to create test
|
||||
entities in your newly deployed system. See the [first steps tutorial](./first-steps-tutorial.md)
|
||||
for more information.
|
||||
|
||||
[app-engine-sdk]: https://cloud.google.com/appengine/docs/java/download
|
||||
[java-jdk11]: https://www.oracle.com/java/technologies/javase-downloads.html
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue