How is the best way to edit rock-ons?


I need change rock-ons Nginx-proxy-manager and owncloud. I must change configuration files in docker image for performance tunning.
I can not find dockerfile or docker-compose definition in my Rockstor.Where are they?

I know that, I can enter to running container and edit file, but container will loss change after restar.

Please help.

Hi @rejt, and welcome to the community!

Thanks for asking such questions ; I’m unfortunately too short on time at the moment to write you a proper answer (will try some time later), but what you want is to look at how to write your own rock-on. Indeed, by writing a new/customized rock-on based on the definition present in the rock-ons catalogue, you should be able to run what you need.

I will thus refer you to our documentation on how to write your own rock-on that you can find in our rock-on registry repository:

I apologize for not having the time to be more helpful at the moment, but the document linked above should put you on the right path. Don’t hesitate to come back here with more questions and details about what you are looking to customized, for instance.



Thank you.

In documentation is being existed path /opt/rockstor/rockons-metastore/. The patch did not exist in my Rockstore. I did not find [app].json from default installation.
I created rockons-metastore directory and test json file. It working.

I would like to repeat the original question, and ask for help with creating/debugging my local rockons.

The instructions in do not seem to be correct anymore, as adding .json files in /opt/rockstor/rockons-metastore and hitting “Update” button in the RockStor UI does nothing.

There is some enthusiasm here for helping with the RockOns development - please make use of it and give us some simple initial instructions how to proceed.

Hi @pepsov, and welcome!

Thanks a lot for reaching out; let’s see if we can help you move forward. I indeed just tested again to make and adding your own Rock-ons to the rockons-metastore does work so let’s try to see if I can help you here.

First, as an illustration of the instructions to which you linked, here’s what I did to test that:

  1. Create the rockons-metastore directory:
mkdir -p /opt/rockstor/rockons-metastore
  1. Copy your own json file. There are many ways to do this and copy the file there. In this case, I’m using a custom JSON for a Rock-on that I use for development: it is named Alpine_AddStorage_2Ports.json:
rockdev-leap15-3:~ # cd /opt/rockstor/rockons-metastore/
# Create the JSON file
rockdev-leap15-3:/opt/rockstor/rockons-metastore # nano Alpine_AddStorage_2Ports.json
# Paste the JSON content and then save. This results in:
rockdev-leap15-3:/opt/rockstor/rockons-metastore # cat Alpine_AddStorage_2Ports.json 
        "Alpine With AddStorage 2Ports": {
                "containers": {
                        "alpine2p1": {
                                "image": "alpine",
                                "launch_order": 1,
                                "opts": [
                                "ports": {},
                                "volumes": {},
                                "environment": {}
                        "alpine2p2": {
                                "image": "alpine",
                                "launch_order": 2,
                                "opts": [
                                "ports": {},
                                "volumes": {},
                                "environment": {},
                                "ports": {
                                        "9000": {
                                                "description": "Fake WebUI port. Suggested default: 9000",
                                                "host_default": 9000,
                                                "label": "WebUI port",
                                                "protocol": "tcp",
                                                "ui": true
                                        "9100": {
                                                "description": "Fake second port. Suggested default: 9100",
                                                "host_default": 9100,
                                                "label": "Random port",
                                                "protocol": "tcp"
                "description": "Alpine test Rock-on.",
                "ui": {
                        "slug": ""
                "volume_add_support": true,
                "website": "",
                "version": "1.0"
  1. Go to the Rock-ons page in Rockstor’s webUI, and then click the “Update” button. The Rock-on is now listed:

Let’s try to see where our instructions are failing for you, now. Would you be able to share some more details on the steps you have followed? Are they much different than what I listed above?

Thanks for letting us know if there were any unclear parts in the instructions to which you linked so that we can improve them.

Looking forward to getting you going!


Thank you for these instructions, Flox!

Indeed, the described mechanism (with creating /opt/rockstor/rockons-metastore/ and placing a valid .json file there) appears to still be working OK. The keyword seems to be ‘valid’ here. What I was trying was to copy the existing config.v2.json file from the already installed PLEX rockon, and then trying to change some settings (mountpoints), so that I can access an external disk which is not BTRFS formatted, and therefore cannot be added to the PLEX rockon via standard menus (which only accept pre-existing shares, which in turn can only(?) be in BTRFS).

So, the problem was twofold:

  1. Since I copied the .json file from the existing ‘standard’ PLEX rockon, I was effectively trying to use the same docker image as the ‘standard’ PLEX, and that - apparently - is not allowed.
  2. The error message for what was happening in 1) would only come (many) minutes after I attempted my changes, so I was missing it completely.

I think that explains the observed behaviour so far.

The original question still remains unanswered though:
Where does RockStor keep the configuration files for the ‘standard’ rockons?

If we take the example of my modified PLEX .json file, clearly me placing it in
/opt/rockstor/rockons-metastore is equivalent to making it ‘available’ in a repo somewhere. Then, from there, when I click on ‘Install’, and follow the prompts to configure it, Rockstor generates the config.v2.json file under directory
and that .json is used by Docker to start the container when I flip its switch from “OFF” to “ON”.

So, what is the equivalent of /opt/rockstor/rockons-metastore for the ‘standard’ rockons? Is it even stored locally on my server, or is it always fetched from an external repo?


  • Stefan

@pepsov Hello there.
@Flox is far more familiar with the Rock-on system but I can chip in on this one:


They are here:

or more specifically the published counterpart at
These files are then parsed and the infromation translated into database entries.

When you press the update button they are re-read form the interwebs and re-parsed. Otherwise the database entries are used.

Take a look at @Flox excellent technical doc on the Rock-ons system internal workings:


It’s very detailed and well explained.

Well done on sorting out your issue, at least in part. Always best to use different names / references in your own custom Rock-ons than those in the default ones.

Hope that helps.


Actually, you can use the same docker image, as far as I know, you just need to adjust the container name in the json file, otherwise the conflict can arise, so when you make a copy in the PLEX example, you would e.g. change this area:

"Plex": {
"containers": {
  "": {
    "image": "linuxserver/plex",

and e.g. change to plex-test I usually also change the title (here from “Plex” to “Plex test” for example) that allows me to easily identify whether I am using a copy of an existing Rockon for testing…


Hi @pepsov,

@phillxnet and @Hooverdan already answered pretty much all your questions so I’ll try to cover the few remaining points.

First, a brief confirmation of @Hooverdan’s answer as that was indeed the most important part: you can reuse the same Docker image as many times as you’d like within a given Rock-on or across as many different Rock-ons as you’d like. What needs to be different, however are the Rock-on name and the container name. To follow-up on @Hooverdan’s example, these would be:

  • "Plex": Rock-on name
  • "": container name

Now, let’s try to go back to your unanswered questions/comments:

To make sure I didn’t misunderstand, I just wanted to clarify on a detail here: after placing your custom rock-on JSON definition file into /opt/rockstor/rockons-metastore, you need to click on the Update button in the top right of the Rock-ons page in Rockstor’s webUI to see your new Rock-on appear. Indeed, Rockstor does not “watch” this folder automatically and you need to trigger this update yourself. Without it, Rockstor will not know of anything placed in this folder.

All details for the process are in the wiki post to which @phillxnet linked above but the gist of it is as follows:

  1. When you trigger the “Update” button on the Rock-ons page, Rockstor fetches the list of JSON files in the remote repository (on a Rockstor’s server), then for each json file listed there it reads all the necessary information and feeds it into its database.
  2. Then it checks to see if there is one or more JSON file in /opt/rockstor/rockons-metastore and does the same.
    This is pretty much how the list of available Rock-ons you see in your Rockstor webUI is generated and updated. Note that there have been discussions about reworking this process in order to make it more efficient especially given our list of available Rock-ons has grown substantially since this mechanism was designed.

Hope this helps, and let us know if you have any other question/comment.


Thank you for your explanations, all of you!
Things are getting clearer and clearer :wink:

Here’s some feedback that I’m sure you’ll find useful:

  1. When I edit my .json file in /opt/rockstor/rockons-metastore/ the editor (‘vi’) leaves a swap file in that directory, and when I click on the ‘Update’ button in the UI that swap file is taken as one of the local rock-ons, fails to be interpreted correctly, and therefore disrupts the whole update process.

  2. During the ‘Update’, the only indication that anything is going on is a little ‘recycle’ pair of arrows, circling in the middle of the box (see attached screenshot)Rock-ons_Update
    Unfortunately, these arrows are so tiny that it’s very easy to miss them, assume that something is wrong with the whole process, give up, and try doing something else. A better indicator here will be really useful.


I would like to get back to finding the answer to my question though:

How should I construct my rockon’s .json file for the modified PLEX container, such that I can have my external, non-BTRFS disk seen inside PLEX read-only?

I’ve tried playing with the “volumes” section

“Plex2”: {
“containers”: {”: {

“volumes”: {
“/data2”: {
“label”: “Extra Storage”

but that merely gives me another configuration parameter during 'Install", which can only be linked to an existing BTRFS share.

Can’t I somehow hard-wire a mount point in my personalized PLEX container?

The best way to hardwire something is to use the "opts" object. You can thus use it to define your volumes mounts there. This is what Rockstor does, for instance to bind /etc/localtime to all containers; see below:

["-v", "/etc/localtime:/etc/localtime:ro"]

I picked that example as it also shows you how you can mount it read-only.

Hope this helps, I’ll comment further on your earlier feedback as it definitely is helpful and I’d like to give it the attention it deserves :wink:

1 Like

Very useful indeed!

Nice find! Here’s the relevant part:

As shown above, we assume all files in the local metastore are JSON files and try to open them as such. We could try to better deal with this and simply skip that file if it fails to be loaded as a JSON, for instance.

I’ve created an issue to track this one and see it resolved:

Another good point! We have some big changes coming to our technical background and that will allow to improve this kind of things. That could allows us to have a proper notification system, background running tasks surfacing, etc…

Thanks a lot for all the feedback!


Hey, that trick with the ‘[opts]’ object works perfectly - Thank you, Flox!
Much appreciated the fast and precise responses!