diff --git a/README.md b/README.md index f91602ca..ddb49a39 100644 --- a/README.md +++ b/README.md @@ -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 .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 .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 ``` { "": { @@ -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": { + }, "containers": { "": , "": , ... @@ -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: + +``` +{ + "" + }, + { + "name": "", (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": [:] that's used to execute a command or entrypoint inside the container. see below>, (optional)"ports": { "": , "": , ... @@ -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 ` 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. ``` { @@ -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": "", @@ -96,9 +151,10 @@ 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: @@ -106,15 +162,17 @@ An options object is a list of exactly two elements. (This needs to be improved ["--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: @@ -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 ``` { @@ -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": "",