diff --git a/docs/app-engine-architecture.md b/docs/app-engine-architecture.md index 4513364e6..9fb7a0ced 100644 --- a/docs/app-engine-architecture.md +++ b/docs/app-engine-architecture.md @@ -184,31 +184,32 @@ then the sandbox app would be named 'registry-platform-sandbox'. The full list of environments supported out-of-the-box, in descending order from real to not, is: -* PRODUCTION -- The real production environment that is actually running live +* `PRODUCTION` -- The real production environment that is actually running live TLDs. Since the Domain Registry is a shared registry platform, there need only ever be one of these. -* SANDBOX -- A playground environment for external users to test commands in +* `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](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 off - on new features to be released. This environment can be pushed to frequently - and is where manual testers should be spending the majority of their time. -* CRASH -- Another environment similar to QA, except with no expectations of +* `QA` -- An internal environment used by business users to play with and sign + off on new features to be released. This environment can be pushed to + frequently and is where manual testers should be spending the majority of + their time. +* `CRASH` -- Another environment similar to QA, except with no expectations of data preservation. Crash is used for testing of backup/restore (which brings the entire system down until it is completed) without affecting the QA environment. -* ALPHA -- The developers' playground. Experimental builds are routinely pushed - here in order to test them on a real app running on App Engine. You may end - up wanting multiple environments like Alpha if you regularly experience - contention (i.e. developers being blocked from testing their code on Alpha - because others are already using it). -* LOCAL -- A fake environment that is used when running the app locally on a +* `ALPHA` -- The developers' playground. Experimental builds are routinely + pushed here in order to test them on a real app running on App Engine. You + may end up wanting multiple environments like Alpha if you regularly + experience contention (i.e. developers being blocked from testing their code + on Alpha because others are already using it). +* `LOCAL` -- A fake environment that is used when running the app locally on a simulated App Engine instance. -* UNITTEST -- A fake environment that is used in unit tests, where everything in - the App Engine stack is simulated or mocked. +* `UNITTEST` -- A fake environment that is used in unit tests, where everything + in the App Engine stack is simulated or mocked. ## Release process diff --git a/docs/registry-tool.md b/docs/registry-tool.md index d3915bbee..c8a4b905d 100644 --- a/docs/registry-tool.md +++ b/docs/registry-tool.md @@ -1,3 +1,81 @@ # Registry tool -Information on registry_tool commands. +The registry tool is a command-line registry administration tool that is invoked +using the `registry_tool` command. It has the ability to view and change a +large 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 `registry_tool` +target in the Bazel BUILD file in that package. + +The registry tool is always called with a specific environment to run in using +the -e parameter. This looks like: + + $ registry_tool -e production {command name} {command parameters} + +To see a list of all available commands along with usage information, run +registry_tool without specifying a command name, e.g.: + + $ registry_tool -e alpha + +Note that the documentation for the commands comes from JCommander, which parses +metadata contained within the code to yield documentation. + +## Tech support commands + +There are actually two separate tools, `gtech_tool`, which is a collection of +lower impact commands intended to be used by tech support personnel, and +`registry_tool`, which is a superset of `gtech_tool` that contains additional +commands that are potentially more destructive and can change more aspects of +the system. A full list of `gtech_tool` commands can be found in +`GtechTool.java`, and the additional commands that only `registry_tool` has +access to are in `RegistryTool.java`. + +## 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 IDE such as Eclipse 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.