Github user joeymcallister commented on a diff in the pull request:
https://github.com/apache/geode/pull/583#discussion_r122320074
--- Diff: geode-docs/rest_apps/setup_config.html.md.erb ---
@@ -29,162 +31,233 @@ All Geode REST interface classes and required JAR
files are distributed as a WAR
where _install-dir_ is the server installation directory and _n.n.n_ is a
version number.
-To enable the developer REST API service in Apache Geode, set the
`start-dev-rest-api` Geode property to `true` when starting a data node using
either `gfsh` or the ServerLauncher API. Setting this property to true on a
data node will start up an embedded Jetty server and deploy the REST developer
API WAR file.
+- [Enabling the REST API](#setup_config_enabling_rest)
+- [Starting the REST API Service](#setup_config_starting_rest)
+- [Implementing Authentication for the REST
API](#setup_config_implementing_auth)
+- [Programmatic Startup](#setup_config_implementing_auth)
+
+# <a id="setup_config_enabling_rest" class="no-quick-link"></a>Enabling
the REST API
+
+The REST API service for application development runs only on data nodes;
you cannot run the service on a locator.
+
+To enable the Developer REST API service on a given server, set the
`start-dev-rest-api` property
+to `true` when starting the data node to start an embedded Jetty server
and deploy the Developer REST
+API WAR file on that node. Use either the `gfsh start server` command or
the ServerLauncher API to enable this property.
-**Note:**
-The REST API service for application development runs only on servers; you
cannot use locators to host the developer Geode REST API services.
+## Enabling the REST API on Multiple Nodes
-You can have multiple REST enabled data nodes in a single distributed
system. Each data node should
+You can configure multiple REST enabled data nodes in a single distributed
system. Each data node should
have a separate host name and unique end point. To ensure that the data
node is reachable on a
-machine with multiple NIC addresses, you can use
`http-service-bind-address` to bind an address to
-the REST API service (as well as the other embedded web services such as
Pulse).
+machine with multiple NIC addresses, use `http-service-bind-address` to
bind an address to
+the REST API service (as well as the other embedded web services, such as
Pulse).
-You can also configure the Developer REST API service to run over
-HTTPS by enabling ssl for the `http` component in `gemfire.properties`
-or `gfsecurity.properties` or on server startup:
-See [SSL](../managing/security/ssl_overview.html) for details on
configuring SSL parameters.
-These SSL parameters apply to all HTTP services hosted on the configured
server, which can include the following:
+You can configure the Developer REST API service to run over HTTPS by
enabling SSL for the `http`
+component in `gemfire.properties` or `gfsecurity.properties`, or on server
startup. See
+[SSL](../managing/security/ssl_overview.html) for details on configuring
SSL parameters. These SSL
+parameters apply to all HTTP services hosted on the configured server,
which can include the
+following:
- Developer REST API service
- Management REST API service (for remote cluster management)
- Pulse monitoring tool
-The following procedure starts up a REST API service-enabled Geode
deployment:
+# <a id="setup_config_starting_rest" class="no-quick-link"></a> Starting
the REST API Service
-1. Configure PDX for your cluster. You must configure PDX if either or
both of the following conditions apply:
- - Application peer member caches will access REST-accessible Regions
(resources) with the `Region.get(key)`.
- - Your deployment has persistent regions that must be available as
resources to the REST API. To configure PDX in your cluster, perform the
following steps:
- 1. Start up a locator running the [cluster configuration
service](../configuring/cluster_config/gfsh_persist.html) (enabled by default).
For example:
+To start a REST API service-enabled Geode deployment, configure PDX
serialization for your
+cluster, then start the service on one or more server nodes.
- ``` pre
- gfsh>start locator --name=locator1
- ```
- 2. If your deployment has application peer member caches (for
example, Java clients) that must also access REST-accessible Regions
(resources), use the following gfsh command:
+## Configure PDX for your cluster
- ``` pre
- gfsh>configure pdx --read-serialized=true
- ```
- **Note:**
- You do not need to configure `--read-serialized=true` if no
application peer member caches are accessing the REST-accessible regions
(resources) in your deployment.
- 3. If your deployment contains **persistent regions** that must
be REST-accessible, use the following gfsh command:
+You must configure PDX if either or both of the following conditions
apply:
- ``` pre
- gfsh>configure pdx --disk-store
- ```
- This command sets `pdx` `persistent` equal to true and sets the
disk-store-name to DEFAULT. If desired, specify an existing disk store name as
the value for `--disk-store`.
- 4. If both of the above cases apply to your deployment, then
configure PDX with the following single command:
+- Application peer member caches will access REST-accessible regions
(resources) with `Region.get(key)`.
+- Your deployment has persistent regions that must be available as
resources to the REST API.
- ``` pre
- gfsh>configure pdx --read-serialized=true --disk-store
- ```
+To configure PDX in your cluster, perform the following steps:
- After you have configured PDX for your caches, then proceed with
starting up your REST-enabled servers and other data nodes.
+1. Start up a locator running the [cluster configuration
service](../configuring/cluster_config/gfsh_persist.html) (enabled by default).
For example:
-2. Start a server node with the Geode property `start-dev-rest-api` set
to `true`.
- Optionally, you can also configure a `http-service-bind-address` and
`http-service-port` to
- identify the cache server and specific port that will host REST
services. If you do not specify
- the `http-service-port`, the default port is 7070. If you do not
specify
- `http-service-bind-address`, the HTTP service will bind to all local
addresses by default.
- **Note:** If your application will be running in a VM (as when running
in the cloud, for example), it's good practice to specify
`http-service-bind-address` and `http-service-port`
- so they will be publicly visible. The default values may not be
visible outside the VM in which the application is running.
+ ``` pre
+ gfsh>start locator --name=locator1
+ ```
- For example:
+2. If your deployment has application peer member caches (for example,
Java clients) that must also access REST-accessible Regions (resources), use
the following gfsh command:
``` pre
- gfsh>start server --name=server1 --start-rest-api=true \
- --http-service-port=8080 --http-service-bind-address=localhost
+ gfsh>configure pdx --read-serialized=true
```
- Any server that hosts data, even a server acting as a JMX manager, can
start the developer REST API service. For example, to start the service on a
server that is also a JMX manager, you would run:
+ **Note:**
+ You do not need to configure `--read-serialized=true` if no
application peer member caches are accessing the REST-accessible regions
(resources) in your deployment.
+
+3. If your deployment contains **persistent regions** that must be
REST-accessible, use the following gfsh command:
+
+ ``` pre
+ gfsh>configure pdx --disk-store
+ ```
+ This command sets `pdx` `persistent` equal to true and sets the
disk-store-name to DEFAULT. If desired, specify an existing disk store name as
the value for `--disk-store`.
+
+4. If both of the above cases apply to your deployment, then configure
PDX with the following single command:
``` pre
- gfsh>start server --name=server1 --start-rest-api=true \
- --http-service-port=8080 --http-service-bind-address=localhost \
- --J=-Dgemfire.jmx-manager=true --J=-Dgemfire.jmx-manager-start=true
+ gfsh>configure pdx --read-serialized=true --disk-store
```
- Note that when started as a JMX Manager, the server will also host the
Pulse web application in the same HTTP service.
+ After you have configured PDX for your caches, then proceed with
starting up your REST-enabled servers and other data nodes.
--- End diff --
Change "starting up your" to "starting your"
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
