Bug 949643

Note: With OSE 1.1, the developer console is in tech preview and is not discussed in the official documentation.  Only from OSE 1.2 on will we officially support the developer console.  This bug report concerns the developer console, and so it does not concern the documentation for OSE 1.1.

Description of problem:

To the instructions on "Clearing Broker Application Cache," we need to add instructions on clearing the developer console's cache (after clearing the broker's cache) and perhaps updating the facts on the node (before clearing the caches).

The relevant part of the documentation is Section 3.1:

https://access.redhat.com/site/documentation/en-US/OpenShift_Enterprise/1/html-single/Administration_Guide/index.html#sect-OpenShift_Enterprise-Administration_Guide-Clearing_Broker_Application_Cache

I suggest the following rewrite of Section 3.1:

#v+
Clearing Caches

Several components of OpenShift Enterprise cache certain values for faster retrieval.  For example, the first time a broker host needs the list of cartridges that are available on the nodes, the broker requests this list from the nodes.  The broker caches the response, and when the broker later needs the list, it refers to its cache rather than making additional queries to the nodes.  A consequence of this caching is that if you install a new cartridge, it is unavailable to users until the caches are cleared and the broker retrieves an up-to-date list of cartridges.

This caching is performed in multiple components:

   * Each node maintains a database of facts about that node, which includes a list of installed cartridges.

   * Using MCollective, a broker queries a node's facts database for the list of cartridges and caches the node's response.

   * Using the broker's REST API, the developer console queries the broker for the list of cartridges and caches the broker's response.

The node's database is refreshed automatically once every minute, the broker's cache is refreshed once every six hours, and the console's cache is refreshed once every five minutes.  It is possible to clear these caches manually so that they will be refreshed immediately.  Perform the following procedures in order:

Procedure 3.1. To update the node's facts database:

    On each node host in your OpenShift Enterprise installation, run the following command:

    # /etc/cron.minutely/openshift-facts

Alternatively, because the the refresh rate for the facts database is so frequent, it may be practical simply to wait for one minute after installing the cartridge, and the facts database will automatically be updated.

Procedure 3.2. To clear the broker's cache:

    On each broker host in your OpenShift Enterprise installation, run the following commands:

    # cd /var/www/openshift/broker
    # scl enable ruby193 bundle exec rake tmp:clear

Procedure 3.2. To clear the console's cache:

    On each host on which you have installed the developer console, run the following commands:

    # cd /var/www/openshift/console
    # scl enable ruby193 'bundle exec rake tmp:clear'
#v-

Please edit as you see fit (I know that my writing style has offended the sensibilities of the docs team in the past).

Additional info:

The above incorporates the "scl enable ruby193" prefix to the bundle command for the console because the console uses Ruby 1.9.3.  It also incorporates the same prefix to the bundle command for the broker because the broker will move from using Ruby 1.8.7 with OSE 1.1 to Ruby 1.9.3 with OSE 1.2.