Skip to content

Update Readme to add uid element and container_links object (#445, #468) #472

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
phillxnet merged 7 commits into from
Sep 12, 2025
Merged

Update Readme to add uid element and container_links object (#445, #468) #472

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b07f82c
add uid element and container_links object
Hooverdan96 Sep 11, 2025
f3d18c7
clarification of uid options
Hooverdan96 Sep 11, 2025
487a326
semantic line feeds
Hooverdan96 Sep 12, 2025
d45167f
semantic linefeed suggestion
Hooverdan96 Sep 12, 2025
b3a0947
More semantic line break updates
Hooverdan96 Sep 12, 2025
cfe7856
Sentence case for headings
Hooverdan96 Sep 12, 2025
71f283d
Sentence case for headings
Hooverdan96 Sep 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 84 additions & 24 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,25 @@
# rockon-registry

This repository consists of Rock-on (Docker based apps) configuration profiles
formatted as JSON files. The Rock-on framework of Rockstor parses a well
formatted profile and provides a generic management and workflow such as
install, uninstall, update, start and stop.
This repository consists of Rock-on (Docker based apps) configuration profiles formatted as JSON files.
The Rock-on framework of Rockstor parses a well formatted profile and provides a generic management and workflow such as install, uninstall, update, start and stop.

## Can You Show Me an Example??
## Can you show me an example??

Look at any <name>.json file in this repository. A simpler example is
[syncthing.json](https://github.com/rockstor/rockon-registry/blob/master/syncthing.json). The structure is fairly intuitive though cumbersome. Using existing examples and the description below of the `json` structure should make it clearer on how this framework is organized.
Look at any <name>.json file in this repository.
A simpler example is [syncthing.json](https://github.com/rockstor/rockon-registry/blob/master/syncthing.json).
The structure is fairly intuitive though cumbersome.
Using existing examples and the description below of the `json` structure should make it clearer on how this framework is organized.

## How Can I Add My Own Rock-on?
## How can I add my own Rock-on?

If you are familiar with Docker and know how to deploy docker containers using the command line, you can create a Rock-on for the same with little effort.
You can find instructions in the [Rockstor Documentation](https://rockstor.com/docs/contribute/contribute_rockons.html) both for running your own Rock-on locally, as well as how to contribute to the existing public repository of available Rock-ons

## What Is the Structure of a Rock-on Profile File?
## What is the structure of a Rock-on profile file?

It is a big mass of JSON with nested objects, arrays and values.

### Top Level Structure
### Top level structure
```
{
"<Rock-on name. eg: LSIO-Plex>": {
Expand All @@ -32,6 +32,8 @@ It is a big mass of JSON with nested objects, arrays and values.
"slug":"gui", link to webui becomes ROCKSTOR_IP:PORT/gui with slug value gui
},
(optional)"volume_add_support": true, If the app allows arbitrary Shares to be mapped to the main container>,
(optional)"container_links": { <network object representing links between containers using separate docker networks, see below>
},
"containers": {
"<container1 name>": <container object representing the main container. see below>,
"<container2 name>": <container object representing the second container, if any. see below>, ...
Expand All @@ -40,16 +42,53 @@ It is a big mass of JSON with nested objects, arrays and values.
}
}
```
_N.B. on the container names. If you are adding a net new Rockon that is a newer version of an existing one, or in a multi-container scenario uses a container for which a Rockon already exists (e.g. mariadb), ensure that the container name in your new Rockon is slightly different, otherwise a duplicate error will be thrown when the final json file is imported._
### Structure of a Container Object

Each container object is key'd by its name and nested within "containers" of the top level structure above. A typical container object has the following structure
### Structure of the container_links object

The basic structure of the optional `container_links` is:

```
{
"<target container": [
{
"name": "<Name of new docker network 1 to be created",
"source_container": "<source container 1 that should connect to target container>"
},
{
"name": "<Name of new docker network 2 to be created",
"source_container": "bareos-storage"
},
{
...
}
]
}
```

_N.B. Current restrictions: a source/destination/network combination is considered a unique entry:_

_A destination container can have multiple sources, but each of these connections will generate its own docker network.
This essentially provides only a point-to-point connection._

_In future releases this constraint will be removed, so, like with Rocknets, the network becomes the center and any container defined in the Rockon can be connected to it,
allowing for multi-directional communication._

### Structure of a `container` object

_N.B. on the container names.
If you are adding a net new Rockon that is a newer version of an existing one, or in a multi-container scenario uses a container for which a Rockon already exists (e.g. mariadb),
ensure that the container name in your new Rockon is slightly different,
otherwise a duplicate error will be thrown when the final json file is imported._

Each container object is key'd by its name and nested within "containers" of the top level structure above.
A typical container object has the following structure

```
{
"image": "<docker image. eg: linuxserver/plex>",
(optional)"tag": "tag of the docker image, if any. latest is used by default.>",
"launch_order": "1 or above. If there are multiple containers and they must be started in order, specify here.>",
(optional) "uid": <user>[:<group>] that's used to execute a command or entrypoint inside the container. see below>,
(optional)"ports": {
"<container side port number1>": <port object represending a port mapping between host and container. see below>,
"<port number2>": <another port object, if necessary. see below>, ...
Expand All @@ -71,9 +110,23 @@ Each container object is key'd by its name and nested within "containers" of the
}
```

As it is evident from above, a container object has nested objects for port and volume mappings, container options, command arguments, and environment variables. These are described below.
### `uid` element

### Port Object
The optional 'uid' element represents the `--user` option in the `docker run` command that underlies the Rockon execution.
Unless the container image was specifically developed to run with a non-root user, it will automatically be started with it.
This element allows for specifying a user with which the main process or other commands inside the container will be run.

The available combinations are:
- set to `"uid"=""` or omitted, then no overriding action is taken and the container is started with its default user (typically `root`).
- UID (which can be found running `id <username>` at the command line or via the `Users` page in the WebUI.
- `-1` this indicates to the Rockon service that the UID of the owner from the first share, defined in the `volume` object, is used for the `--user` option.
In future releases, this will be extended to be able to take advantage of the full scope that the `--user` option allows.

As it is evident from above, a `container` object also has nested objects for port and volume mappings, container options, command arguments, and environment variables.
These are described below.

### `ports` Object
This optional object can be used for mapping of external ports onto the ports published by the container image.

```
{
Expand All @@ -84,10 +137,12 @@ As it is evident from above, a container object has nested objects for port and
(optional)"ui":true, not needed if false
}
```
Note that protocol is optional and if it's not present, both tcp and udp ports are mapped simultaneously. So if you wish to allow both tcp and udp, just don't specify protocol in the Port object.

### Volume Object
_Note that protocol is optional and if it's not present, both tcp and udp ports are mapped simultaneously.
If you wish to allow both tcp and udp, just don't specify protocol in the Port object._

### `volumes` Object
This optional object allows the mapping of Rockstor shares onto volume paths exposed by the container image.
```
{
"description": "<A detailed description. Eg: This is where all incoming syncthing data will be stored>",
Expand All @@ -96,25 +151,28 @@ Note that protocol is optional and if it's not present, both tcp and udp ports a
}
```

### Options Object
### `options` object

An options object is a list of exactly two elements. (This needs to be improved or deprecated in favor of more specific design.)
An (optional) options object is a list of exactly two elements.
(This needs to be improved or deprecated in favor of more specific design.)

`--net=host` would be represented as:

```
["--net", "host"]
```

Note that the opts field is a 2-d array, so the complete line for the above example looks like
Note that the `opts` field is a 2-d array, so the complete line for the above example looks like

```
"opts": [ ["--net", "host"] ],
```

### Command Arguments Object
### `cmd` object

A command arguments object is a list of exactly two elements detailing specific arguments to be passed onto the `docker run` command. As these arguments will simply be appended to the `docker run` command, they need to follow the same syntax and order. For instance,
The optional `cmd` (command arguments) object is a list of exactly two elements detailing specific arguments to be passed onto the `docker run` command.
As these arguments will simply be appended to the `docker run` command, they need to follow the same syntax and order.
For instance,

`docker run <...> image/name argument1 argument2="text2"` would be represented as:

Expand All @@ -128,7 +186,8 @@ Note that, as for the options object, the cmd_arguments field is a 2-d array, so
"cmd_arguments": [ ["argument1", "argument2="text2"] ],
```

### Environment Object
### `environment` object
This optional object allows to pass environment variables that are exposed by the container image into the container

```
{
Expand All @@ -139,9 +198,10 @@ Note that, as for the options object, the cmd_arguments field is a 2-d array, so
```


### Devices Object
### `devices` object

This optional object allows to pass a specific device to the Rock-on, and similarly to the Environment object, must have a "description" and "label".

```
{
"description": "<Detailed description of the device and its intent or specificities. Eg: path to device (/dev/xxx)>",
Expand Down