mirror of
https://github.com/google/nomulus.git
synced 2025-04-30 03:57:51 +02:00
bc03a01388
We are no longer using Eclipse internally and therefore stopped maintaining stuff related to it. We cannot guarantee that any pertinent information remains correct and relevant in the future. Users are advised to use IntelliJ (Community Edition is fine) with Bazel plugin if they want IDE support. ------------- Created by MOE: https://github.com/google/moe MOE_MIGRATED_REVID=189586127
104 lines
5 KiB
Markdown
104 lines
5 KiB
Markdown
# Admin tool
|
|
|
|
Nomulus includes a command-line registry administration tool that is invoked
|
|
using the `nomulus` command. It has the ability to view and change a large
|
|
number of things in a live Nomulus 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` target
|
|
in the Bazel BUILD file in that package.
|
|
|
|
The tool connects to the Google Cloud Platform project (identified by project
|
|
ID) that was configured in your implementation of `RegistryConfig` when the tool
|
|
was built. See the [configuration guide](./configuration.md) for more
|
|
information. The tool can switch between project IDs that represent different
|
|
environments within a single overall platform (i.e. the production environment
|
|
plus development and testing environments); see the `-e` parameter below. For
|
|
example, if the platform is called "acme-registry", then the production project
|
|
ID is also "acme-registry", and the project ID for the sandbox environment is
|
|
"acme-registry-sandbox".
|
|
|
|
## Build the tool
|
|
|
|
To build the `nomulus` tool, execute the following `bazel build` command inside
|
|
any directory of the codebase. You must rebuild the tool any time that you edit
|
|
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:
|
|
|
|
```shell
|
|
$ nomulus -e production {command name} {command parameters}
|
|
```
|
|
|
|
You can get help about the tool in general, or about a specific subcommand, as
|
|
follows:
|
|
|
|
```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.
|
|
|
|
## Local and server-side commands
|
|
|
|
There are two broad ways that commands are implemented: some that send requests
|
|
to `ToolsServlet` to execute the action on the server (these commands implement
|
|
`ServerSideCommand`), and others that execute the command locally using the
|
|
[Remote API](https://cloud.google.com/appengine/docs/java/tools/remoteapi)
|
|
(these commands implement `RemoteApiCommand`). Server-side commands take more
|
|
work to implement because they require both a client and a server-side
|
|
component, e.g. `CreatePremiumListCommand.java` and
|
|
`CreatePremiumListAction.java` respectively for creating a premium list.
|
|
However, they are fully capable of doing anything that is possible with App
|
|
Engine, including running a large MapReduce, because they execute on the tools
|
|
service in the App Engine cloud.
|
|
|
|
Local commands, by contrast, are easier to implement, because there is only a
|
|
local component to write, but they aren't as powerful. A general rule of thumb
|
|
for making this determination is to use a local command if possible, or a
|
|
server-side command otherwise.
|
|
|
|
## Common tool patterns
|
|
|
|
All tools ultimately implement the `Command` interface located in the `tools`
|
|
package. If you use an integrated development environment (IDE) such as IntelliJ
|
|
to view the type hierarchy of that interface, you'll see all of the commands
|
|
that exist, as well as how a lot of them are grouped using sub-interfaces or
|
|
abstract classes that provide additional functionality. The most common patterns
|
|
that are used by a large number of other tools are:
|
|
|
|
* **`BigqueryCommand`** -- Provides a connection to BigQuery for tools that
|
|
need it.
|
|
* **`ConfirmingCommand`** -- Provides the methods `prompt()` and `execute()`
|
|
to override. `prompt()` outputs a message (usually what the command is going
|
|
to do) and prompts the user to confirm execution of the command, and then
|
|
`execute()` actually does it.
|
|
* **`EppToolCommand`** -- Commands that work by executing EPP commands against
|
|
the server, usually by filling in a template with parameters that were
|
|
passed on the command-line.
|
|
* **`MutatingEppToolCommand`** -- A sub-class of `EppToolCommand` that
|
|
provides a `--dry_run` flag, that, if passed, will display the output from
|
|
the server of what the command would've done without actually committing
|
|
those changes.
|
|
* **`GetEppResourceCommand`** -- Gets individual EPP resources from the server
|
|
and outputs them.
|
|
* **`ListObjectsCommand`** -- Lists all objects of a specific type from the
|
|
server and outputs them.
|
|
* **`MutatingCommand`** -- Provides a facility to create or update entities in
|
|
Datastore, and uses a diff algorithm to display the changes that will be
|
|
made before committing them.
|