This wiki entry is intended as a overview of the process required to test a proposed Rock-on; ie one that currently exists within a GitHub Pull request. Please edit with care as you see fit as this wiki guide, like the rest of Rockstor, is a community focused effort. Comments should be constrained to content suggestions only. Thanks.
Rockstor’s Rock-on registry / repositor is almost entirely contributor populated and by way of due diligence each submission (pull request in GitHub speak) requires at least a cursory functional check. It is not expected that this check be carried out by an expert in the application or technology area that the new / modified Rock-on exists within as this would be entirely impractical. However if you are an expert then that’s great.
Each Rock-on must first be contributed via GitHub by following the process detailed in the Rock-on registry / repository README.md file. That process is almost always more involved / technical that the process of testing a existing proposed rock-on, this is down to the Rock-on system being a simple wrapper around an existing docker image definition file. These files are from the user perspective retrieved invisibly from the Rock-on registry. But there is a procedure, also detailed in the README.md already linked where by on can add / run non registry Rock-on definitions. This wiki will repeat some information given in that document for the sake of clarity but from a less technical point of view as it is often, but not always, an easier task to test an Rock-on than to develop it.
Assuming you already have a configured and enabled Rock-on configuration see:
http://rockstor.com/docs/docker-based-rock-ons/overview.html
The test procedure involves the following 4 steps.
1. Create the local repo directory
Simply a directory created using the following command (run as the root user):
mkdir /opt/rockstor/rockons-metastore
If the directory already exists then the command output will state this; no harm done.
2. Retrieve the proposed Rock-on file:
This is a less than elegant but simple process:
Each Rock-on is defined by a single json file (ie ending in “.json”) but the file must be in a raw form. By default GitHub shows a ‘web page’ view of the file so we have to get the file’s raw url (web link). To do this we first click on the Rock-on pull request we want to test. These are found here:
https://github.com/rockstor/rockon-registry/pulls
And having selected a particular pull request we then click on it’s Files Changed tab:
There is usually only 1 file in the 'Files Changed ’ tab but there can, on occasions, be another. The one we are interested in is the one ending in “.json”. Click on the View button by this file’s name.
Then on the subsequent Raw button:
The browser url bar (if activated) should then display the address we are after. It will be of the following form:
https://raw.githubusercontent.com/rockstor/rockon-registry/.../rock-on-name.json
Where the “…” bit is a long string specific to the particular pull request.
Now that we have this long url we can ‘webget’ the proposed Rock-on (json file) directly into our freshly created or pre-existing rockons-metastore directory via the following commands (executed as the root user):
cd /opt/rockstor/rockons-metastore
wget https://raw.githubusercontent.com/rockstor/rockon-registry//netdata.json
3. Install the proposed Rock-on
Now that our system has the proposed Rock-on definition file installed locally we can test to see if it appears as a new option in the Rock-ons page All tab. Note that an Update button click will be required for the new Rock-on to show up:
There after the All tab should now include an additional entry:
In this example we now see the proposed (as of writing) Netdata Rockon entry. Any typos in this text can be noted in the pull requests comments section but be aware that they are usually purely cosmetic and it will have take the contributor valuable time to have gotten this far so let’s not be too picky as the main ‘purpose’ here is to test the basic functionality of the proposed Rock-on: ie does it install and does it run as expected.
From here on the Install is as per usual for a Rock-on, ie click the install button and wing it, ie: follow the on screen instructions and if necessary create the indicated shares and users if required. There are examples of how some of the existing Rock-ons appear during install in the following doc section:
Our particular example required a single share with no special user ownership.
If all went well then the Installed tab should now have an additional entry akin to the prior “All” tab entry eg:
The minority of Rock-ons will require additional configuration steps prior to them ‘turning on’ by default, the information icon “i” should give this advise if it is required.
In this example we have a successful install as we have Current status: started. If this is not your experience then discuss your indicated outcome cordially in the pull requests comment section.
4. Does it work / run
This can be a tricky question as each rock-on / docker image is different but in our case we are expecting output akin to that demonstrated on the page arrived at by clicking on the Rock-ons name. Note that this is sometimes a link to the docker image creators page but should in most cases, in turn, lead to the ‘parent’ project and it’s associated screenshots / descriptions.
Clicking on in this case the Netdata UI button looks to have provided the expected outcome. That of the Netdata Web-UI landing page:
Nice.
Now all that remains is to post your findings / experience regarding the pending Rock-on pull request. Again it is very important to be cordial here. And it may be helpful to attach (drag and drop) a screen shot.
Thanks
Your efforts in testing new / modified Rock-ons is crucial to their continued growth and, akin to the Rockstor project as a whole, is very much dependant, as an open source project, on user participation / support.