mirrors/nomulus
1
0
Fork 0
mirror of https://github.com/google/nomulus synced 2026-08-19 21:56:17 +00:00
Code Issues Releases Wiki Activity

Update more of the documentation (#2974)

Browse Source 
We should be at least at a "good enough" state after this -- I'm sure
there are many updates we could make that would improve the
documentation but this is definitely much improved from before and
should hopefully be good enough to get people started.
This commit is contained in:
gbrodman
2026-03-03 20:25:30 +00:00
committed by GitHub
parent 25fcef8a5b
commit 72016b1e5f
6 changed files with 461 additions and 598 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/configuration.md
+85 -83
View File
@@ -2,10 +2,11 @@
There are multiple different kinds of configuration that go into getting a
working registry system up and running. Broadly speaking, configuration works in
two ways -- globally, for the entire sytem, and per-TLD. Global configuration is
managed by editing code and deploying a new version, whereas per-TLD
configuration is data that lives in the database in `Tld` entities, and is
updated by running `nomulus` commands without having to deploy a new version.
two ways -- globally, for the entire system, and per-TLD. Global configuration
is managed by editing code and deploying a new version, whereas per-TLD
configuration is data that lives in the database in `Tld` entities, and
[is updated](operational-procedures/modifying-tlds.md) without having to deploy
a new version.
## Initial configuration
@@ -23,40 +24,14 @@ Before getting into the details of configuration, it's important to note that a
lot of configuration is environment-dependent. It is common to see `switch`
statements that operate on the current `RegistryEnvironment`, and return
different values for different environments. This is especially pronounced in
the `UNITTEST` and `LOCAL` environments, which don't run on App Engine at all.
As an example, some timeouts may be long in production and short in unit tests.
the `UNITTEST` and `LOCAL` environments, which don't run on GCP at all. As an
example, some timeouts may be long in production and short in unit tests.
See the [Architecture documentation](./architecture.md) for more details on
environments as used by Nomulus.
## App Engine configuration
App Engine configuration isn't covered in depth in this document as it is
thoroughly documented in the [App Engine configuration docs][app-engine-config].
The main files of note that come pre-configured in Nomulus are:
* `cron.xml` -- Configuration of cronjobs
* `web.xml` -- Configuration of URL paths on the webserver
* `appengine-web.xml` -- Overall App Engine settings including number and type
of instances
* `cloud-scheduler-tasks.xml` -- Configuration of Cloud Scheduler Tasks
* * `cloud-tasks-queue.xml` -- Configuration of Cloud Tasks Queue
* `application.xml` -- Configuration of the application name and its services
Cron, web, and queue are covered in more detail in the "App Engine architecture"
doc, and the rest are covered in the general App Engine documentation.
If you are not writing new code to implement custom features, is unlikely that
you will need to make any modifications beyond simple changes to
`application.xml` and `appengine-web.xml`. If you are writing new features, it's
likely you'll need to add cronjobs, URL paths, and task queues, and thus edit
those associated XML files.
The existing codebase is configured for running a full-scale registry with
multiple TLDs. In order to deploy to App Engine, you will either need to
[increase your quota](https://cloud.google.com/compute/quotas#requesting_additional_quota)
to allow for at least 100 running instances or reduce `max-instances` in the
backend `appengine-web.xml` files to 25 or less.
TODO: documentation about how to set up GKE and what config points are necessary
to modify there
## Global configuration
@@ -65,9 +40,9 @@ deployed in the app. The full list of config options and their default values
can be found in the [`default-config.yaml`][default-config] file. If you wish to
change any of these values, do not edit this file. Instead, edit the environment
configuration file named
`google/registry/config/files/nomulus-config-ENVIRONMENT.yaml`, overriding only
the options you wish to change. Nomulus ships with blank placeholders for all
standard environments.
`core/src/main/java/google/registry/config/files/nomulus-config-ENVIRONMENT.yaml`,
overriding only the options you wish to change. Nomulus ships with blank
placeholders for all standard environments.
You will not need to change most of the default settings. Here is the subset of
settings that you will need to change for all deployed environments, including
@@ -75,52 +50,65 @@ development environments. See [`default-config.yaml`][default-config] for a full
description of each option:
```yaml
appEngine:
projectId: # Your App Engine project ID
toolsServiceUrl: https://tools-dot-PROJECT-ID.appspot.com # Insert your project ID
isLocal: false # Causes saved credentials to be used.
gcpProject:
projectId: # Your GCP project ID
projectIdNumber: # The corresponding ID number, found on the home page
locationId: # e.g. us-central1
isLocal: false # Causes saved credentials to be used
baseDomain: # the base domain from which the registry will be served, e.g. registry.google
gSuite:
domainName: # Your G Suite domain name
adminAccountEmailAddress: # An admin login for your G Suite account
domainName: # Your GSuit domain name, likely same as baseDomain above
adminAccountEmailAddress: # An admin login for your GSuite account
auth:
allowedServiceAccountEmails:
- # a list of service account emails given access to Nomulus
oauthClientId: # the client ID of the Identity-Aware Proxy
cloudSql:
jdbcUrl: # path to the Postgres server
```
For fully-featured production environments that need the full range of features
(e.g. RDE, correct contact information on the registrar console, etc.) you will
need to specify more settings.
need to specify *many* more settings.
From a code perspective, all configuration settings ultimately come through the
[`RegistryConfig`][registry-config] class. This includes a Dagger module called
`ConfigModule` that provides injectable configuration options. While most
configuration options can be changed from within the yaml config file, certain
derived options may still need to be overriden by changing the code in this
derived options may still need to be overridden by changing the code in this
module.
## OAuth 2 client id configuration
## OAuth 2 client ID configuration
The open source Nomulus release uses OAuth 2 to authenticate and authorize
users. This includes the `nomulus` tool when it connects to the system to
execute commands. OAuth must be configured before you can use the `nomulus` tool
to set up the system.
Nomulus uses OAuth 2 to authenticate and authorize users. This includes the
`nomulus` [command-line tool](admin-tool.md) when it connects to the system to
execute commands as well as the
[Identity-Aware Proxy](https://pantheon.corp.google.com/security/iap) used to
authenticate standard requests. OAuth must be configured before you can use
either system.
OAuth defines the concept of a *client id*, which identifies the application
OAuth defines the concept of a *client ID*, which identifies the application
which the user wants to authorize. This is so that, when a user clicks in an
OAuth permission dialog and grants access to data, they are not granting access
to every application on their computer (including potentially malicious ones),
but only to the application which they agree needs access. Each environment of
the Nomulus system should have its own client id. Multiple installations of the
`nomulus` tool application can share the same client id for the same
environment.
the Nomulus system should have its own pair of client IDs. Multiple
installations of the `nomulus` tool application can share the same client ID for
the same environment.
There are three steps to configuration.
For the Nomulus tool OAuth configuration, do the following steps:
* **Create the client id in App Engine:** Go to your project's
* **Create the registry tool client ID in GCP:** Go to your project's
["Credentials" page](https://console.developers.google.com/apis/credentials)
in the Developer's Console. Click "Create credentials" and select "OAuth
client ID" from the dropdown. In the create credentials window, select an
application type of "Desktop app". After creating the client id, copy the
client id and client secret which are displayed in the popup window. You may
also obtain this information by downloading the json file for the client id.
application type of "Desktop app". After creating the client ID, copy the
client ID and client secret which are displayed in the popup window. You may
also obtain this information by downloading the JSON file for the client ID
* **Copy the client secret information to the config file:** The *client
secret file* contains both the client ID and the client secret. Copy the
@@ -129,18 +117,21 @@ There are three steps to configuration.
`registryTool` section. This will make the `nomulus` tool use this
credential to authenticate itself to the system.
* **Add the new client id to the configured list of allowed client ids:** The
configuration files include an `oAuth` section, which defines a parameter
called `allowedOauthClientIds`, specifying a list of client ids which are
permitted to connect. Add the client ID to the list. You will need to
rebuild and redeploy the project so that the configuration changes take
effect.
For IAP configuration, do the following steps: * **Create the IAP client ID:**
Follow similar steps from above to create an additional OAuth client ID, but
using an application type of "Web application". Note the client ID and secret. *
**Enable IAP for your HTTPS load balancer:** On the
[IAP page](https://pantheon.corp.google.com/security/iap), enable IAP for all of
the backend services that all use the same HTTPS load balancer. * **Use a custom
OAuth configuration:** For the backend services, under the "Settings" section
(in the three-dot menu) enable custom OAuth and insert the client ID and secret
that we just created * **Save the client ID:** In the configuration file, save
the client ID as `oauthClientId` in the `auth` section
Once these steps are taken, the `nomulus` tool will use a client id which the
server is configured to accept, and authentication should succeed. Note that
many Nomulus commands also require that the user have App Engine admin
privileges, meaning that the user needs to be added as an owner or viewer of the
App Engine project.
Once these steps are taken, the `nomulus` tool and IAP will both use client IDs
which the server is configured to accept, and authentication should succeed.
Note that many Nomulus commands also require that the user have GCP admin
privileges on the project in question.
## Sensitive global configuration
@@ -151,8 +142,8 @@ control mishap. We use a secret store to persist these values in a secure
manner, which is backed by the GCP Secret Manager.
The `Keyring` interface contains methods for all sensitive configuration values,
which are primarily credentials used to access various ICANN and ICANN-
affiliated services (such as RDE). These values are only needed for real
which are primarily credentials used to access various ICANN and
ICANN-affiliated services (such as RDE). These values are only needed for real
production registries and PDT environments. If you are just playing around with
the platform at first, it is OK to put off defining these values until
necessary. This allows the codebase to start and run, but of course any actions
@@ -169,16 +160,16 @@ ${KEY_NAME}`.
## Per-TLD configuration
`Tld` entities, which are persisted to the database, are used for per-TLD
configuration. They contain any kind of configuration that is specific to a TLD,
such as the create/renew price of a domain name, the pricing engine
implementation, the DNS writer implementation, whether escrow exports are
enabled, the default currency, the reserved label lists, and more. The `nomulus
update_tld` command is used to set all of these options. See the
[admin tool documentation](./admin-tool.md) for more information, as well as the
command-line help for the `update_tld` command. Unlike global configuration
above, per-TLD configuration options are stored as data in the running system,
and thus do not require code pushes to update.
`Tld` entities, which are persisted to the database and stored in YAML files,
are used for per-TLD configuration. They contain any kind of configuration that
is specific to a TLD, such as the create/renew price of a domain name, the
pricing engine implementation, the DNS writer implementation, whether escrow
exports are enabled, the default currency, the reserved label lists, and more.
To create or update TLDs, we use
[YAML files](operational-procedures/modifying-tlds.md) and the `nomulus
configure_tld` command. Because the TLDs are stored as data in the running
system, they do not require code pushes to update.
[app-engine-config]: https://cloud.google.com/appengine/docs/java/configuration-files
[default-config]: https://github.com/google/nomulus/blob/master/java/google/registry/config/files/default-config.yaml
@@ -242,7 +233,7 @@ connectionName: your-project:us-central1:nomulus
Use the `update_keyring_secret` command to update the `SQL_PRIMARY_CONN_NAME`
key with the connection name. If you have created a read-replica, update the
`SQL_REPLICA_CONN_NAME` key with the replica's connection time.
`SQL_REPLICA_CONN_NAME` key with the replica's connection name.
### Installing the Schema
@@ -334,6 +325,17 @@ $ gcloud sql connect nomulus --user=nomulus
From this, you should have a postgres prompt and be able to enter the "GRANT"
command specified above.
### Replication and Backups
We highly recommend creating a read-only replica of the database and using the
previously-mentioned `SQL_REPLICA_CONN_NAME` value in the keyring to the name of
that replica. By doing so, you can remove some load from the primary database.
We also recommend enabling
[point-in-time recovery](https://docs.cloud.google.com/sql/docs/postgres/backup-recovery/pitr)
for the instance, just in case something bad happens and you need to restore
from a backup.
### Cloud SecretManager
You'll need to enable the SecretManager API in your project.