geode-docs/rest_apps/setup_config.html.md.erb - geode - Git at Google

 ---
 title:  Setup and Configuration
 ---

 <!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 -->

 The Apache Geode developer REST interface runs as an embedded HTTP or HTTPS service (Jetty server) within a Geode data node.

 All Geode REST interface classes and required JAR files are distributed as a WAR file with the Geode product distribution. You can locate the file in the following location:

 ``` pre
 $GEMFIRE/tools/Extensions/gemfire-api.war
 ```

 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.

 **Note:**
 The REST API service for application development can only be started on servers; you cannot use locators to host the developer Geode REST API services.

 You can have 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.)

 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:

 -   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:

 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:

             ``` 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:

             ``` 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:

             ``` 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>configure pdx --read-serialized=true --disk-store
             ```

     After you have configured PDX for your caches, then proceed with starting up your REST-enabled servers and other data nodes.

 2.  Start a server node with the Geode property `start-dev-rest-api` set to `true`. For example:

     ``` pre
     gfsh>start server --name=server1 --J=-Dgemfire.start-dev-rest-api=true \
     --J=-Dgemfire.http-service-port=8080 --J=-Dgemfire.http-service-bind-address=localhost
     ```

     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.

     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:

     ``` pre
     gfsh>start server --name=server1  --J=-Dgemfire.start-dev-rest-api=true \
     --J=-Dgemfire.http-service-port=8080 --J=-Dgemfire.http-service-bind-address=localhost \
     --J=-Dgemfire.jmx-manager=true --J=-Dgemfire.jmx-manager-start=true
     ```

     Note that when started as a JMX Manager, the server will also host the Pulse web application in the same HTTP service.

 3.  You may also need to specify a CLASSPATH to load any functions that need to be made available to your REST services. For example:

     ``` pre
     gfsh>start server --name=server1 --J=-Dgemfire.start-dev-rest-api=true \
     --J=-Dgemfire.http-service-port=8080 --J=-Dgemfire.http-service-bind-address=localhost \
     --classpath=/myapps/testfunctions.jar
     ```

 4.  You can also specify these properties either upon server startup or in the server’s gemfire.properties configuration file.

     ``` pre
     gfsh>start server --name=serverX --server-port=40405 --cache-xml-file=cache-config.xml \
     --properties-file=gemfire.properties --classpath=/myapps/testfunctions.jar
     ```

     where gemfire.properties contains:

     ``` pre
     http-service-port=8080
     http-service-bind-address=localhost
     start-dev-rest-api=true
     ```

 5.  Verify that the Geode REST API service is up and running. To validate this, you can perform the following checks:
     1.  Test the list resources endpoint (this step assumes that you have regions defined on your cluster):

         ``` pre
         curl -i http://localhost:8080/gemfire-api/v1
         ```

     2.  Examine the server logs for the following messages:

         ``` pre
         [info 2014/06/12 14:56:52.431 PDT rest-test <localhost-startStop-1> tid=0x4d]
         (tid=11 msgId=8) Initializing Spring FrameworkServlet 'gemfire-api'[info 2014/06/12
         14:56:52.432 PDT rest-test <localhost-startStop-1> tid=0x4d] (tid=11 msgId=9)
         FrameworkServlet 'gemfire-api': initialization started
         ```

     3.  Open a browser and enter the following URL to browse the Swagger-enabled REST APIs:

         ``` pre
         http://<http-service-bind-address>:<http-service-port>/gemfire-api/docs/index.html
         ```

         where *http-service-bind-address* is the address and *http-service-port* is the port number that you specified when starting the Development REST API service on the server. For example, based on the server started in step 2, you would enter:

         ``` pre
         http://localhost:8080/gemfire-api/docs/index.html
         ```

         If you did not specify these properties upon server startup or in `gemfire.properties`, then use the default of localhost and port 7070. See [Using the Swagger UI to Browse REST APIs](using_swagger.html#concept_rlr_y3c_54) for more information.

 ## Programmatic Startup

 You can also start up and configure Geode REST services programmatically. For example:

 ``` pre
     import org.apache.geode.distributed.ServerLauncher;

      public class MyEmbeddedRestServer {

      public static void main(String[] args){
          ServerLauncher serverLauncher  = new ServerLauncher.Builder()
            .set("start-dev-rest-api", "true")
            .set("http-service-port", "8080")
            .set("http-service-bind-address", "localhost")
            .setPdxReadSerialized(true)
            .build();

           serverLauncher.start();

           System.out.println("REST server successfully started");
         }
     }
 ```
 You can then verify that the developer REST API service has been started programmatically by visiting the following URL:

 ``` pre
 http://localhost:8080/gemfire-api/docs/index.html
 ```
	---
	title: Setup and Configuration
	---

	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->

	The Apache Geode developer REST interface runs as an embedded HTTP or HTTPS service (Jetty server) within a Geode data node.

	All Geode REST interface classes and required JAR files are distributed as a WAR file with the Geode product distribution. You can locate the file in the following location:

	``` pre
	$GEMFIRE/tools/Extensions/gemfire-api.war
	```

	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.

	Note:
	The REST API service for application development can only be started on servers; you cannot use locators to host the developer Geode REST API services.

	You can have 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.)

	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:

	- 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:

	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:

	``` 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:

	``` 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:

	``` 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>configure pdx --read-serialized=true --disk-store
	```

	After you have configured PDX for your caches, then proceed with starting up your REST-enabled servers and other data nodes.

	2. Start a server node with the Geode property `start-dev-rest-api` set to `true`. For example:

	``` pre
	gfsh>start server --name=server1 --J=-Dgemfire.start-dev-rest-api=true \
	--J=-Dgemfire.http-service-port=8080 --J=-Dgemfire.http-service-bind-address=localhost
	```

	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.

	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:

	``` pre
	gfsh>start server --name=server1 --J=-Dgemfire.start-dev-rest-api=true \
	--J=-Dgemfire.http-service-port=8080 --J=-Dgemfire.http-service-bind-address=localhost \
	--J=-Dgemfire.jmx-manager=true --J=-Dgemfire.jmx-manager-start=true
	```

	Note that when started as a JMX Manager, the server will also host the Pulse web application in the same HTTP service.

	3. You may also need to specify a CLASSPATH to load any functions that need to be made available to your REST services. For example:

	``` pre
	gfsh>start server --name=server1 --J=-Dgemfire.start-dev-rest-api=true \
	--J=-Dgemfire.http-service-port=8080 --J=-Dgemfire.http-service-bind-address=localhost \
	--classpath=/myapps/testfunctions.jar
	```

	4. You can also specify these properties either upon server startup or in the server’s gemfire.properties configuration file.

	``` pre
	gfsh>start server --name=serverX --server-port=40405 --cache-xml-file=cache-config.xml \
	--properties-file=gemfire.properties --classpath=/myapps/testfunctions.jar
	```

	where gemfire.properties contains:

	``` pre
	http-service-port=8080
	http-service-bind-address=localhost
	start-dev-rest-api=true
	```

	5. Verify that the Geode REST API service is up and running. To validate this, you can perform the following checks:
	1. Test the list resources endpoint (this step assumes that you have regions defined on your cluster):

	``` pre
	curl -i http://localhost:8080/gemfire-api/v1
	```

	2. Examine the server logs for the following messages:

	``` pre
	[info 2014/06/12 14:56:52.431 PDT rest-test <localhost-startStop-1> tid=0x4d]
	(tid=11 msgId=8) Initializing Spring FrameworkServlet 'gemfire-api'[info 2014/06/12
	14:56:52.432 PDT rest-test <localhost-startStop-1> tid=0x4d] (tid=11 msgId=9)
	FrameworkServlet 'gemfire-api': initialization started
	```

	3. Open a browser and enter the following URL to browse the Swagger-enabled REST APIs:

	``` pre
	http://<http-service-bind-address>:<http-service-port>/gemfire-api/docs/index.html
	```

	where http-service-bind-address is the address and http-service-port is the port number that you specified when starting the Development REST API service on the server. For example, based on the server started in step 2, you would enter:

	``` pre
	http://localhost:8080/gemfire-api/docs/index.html
	```

	If you did not specify these properties upon server startup or in `gemfire.properties`, then use the default of localhost and port 7070. See [Using the Swagger UI to Browse REST APIs](using_swagger.html#concept_rlr_y3c_54) for more information.

	## Programmatic Startup

	You can also start up and configure Geode REST services programmatically. For example:

	``` pre
	import org.apache.geode.distributed.ServerLauncher;

	public class MyEmbeddedRestServer {

	public static void main(String[] args){
	ServerLauncher serverLauncher = new ServerLauncher.Builder()
	.set("start-dev-rest-api", "true")
	.set("http-service-port", "8080")
	.set("http-service-bind-address", "localhost")
	.setPdxReadSerialized(true)
	.build();

	serverLauncher.start();

	System.out.println("REST server successfully started");
	}
	}
	```
	You can then verify that the developer REST API service has been started programmatically by visiting the following URL:

	``` pre
	http://localhost:8080/gemfire-api/docs/index.html
	```