Define default folder structure #35
Conversation
After extensive discussion with someone trying to make RAMS work with their own infrastructure, it's clear that defining how the RAMS + Sideboard app is actually structured would be very helpful to developers. This is kind of a weird place to put it but this readme is the best we've got for decent documentation right now.
|
|
||
| Currently, all configuration for the app is defined in four files: | ||
| * `/uber/configspec.ini` declares the static variables and includes in-line explanations of each. | ||
| * `/development-defaults.ini` sets up sane defaults for an example event. | ||
| * `/development.ini`, which is not checked into Git, can be used to override any config option in your local environment. | ||
| * `/uber/config.py` processes these variables and inserts them into a global `c` object. Config.py also defines dynamic variables and properties, which are also added to the `c` object. | ||
|
|
||
| ### RAMS Structure | ||
| If you use this repo, a lot of RAMS' native structure will be altered. For example, Sideboard is its own Docker container, so you will not see it. However, it is useful to know what the actual file structure would be if you installed RAMS 'bare' on your machine by cloning the Sideboard repository, then cloning the RAMS repository and other RAMS plugins into Sideboard's plugins folder (see below). |
There was a problem hiding this comment.
The native structure is still there, it's just inside the container. "Altered" gives the wrong idea I think.
| * `development.ini`: called sideboard-development.ini in Quickstart, this is a config file for Sideboard. You might use this to control the order in which plugins are loaded. | ||
| * `plugins` | ||
| * `rams` | ||
| * `development.ini`: called development.ini in Quickstart, this is the config file for RAMS mentioned above. |
There was a problem hiding this comment.
Note that we are getting away from a development.ini existing and just using development-defaults.ini - this should probably also include a description of how configspec.ini, development-defaults.ini, and development.ini interact.
| * `plugins` | ||
| * `rams` | ||
| * `development.ini`: called development.ini in Quickstart, this is the config file for RAMS mentioned above. | ||
| * `uber`: this contains the bulk of the RAMS app. Most code changes would be in this folder. |
There was a problem hiding this comment.
Also we may want to note that the uber directory:
- Must be named
uberand lots of stuff breaks if you rename it! - Is its own Git repo. (and each other plugin is its own repo as well) Not sure if this is the best place to mention this or not but it should be somewhere.
There was a problem hiding this comment.
- Yup, I'll add that.
- That's the folder above this one, which I named
ramshere (I guess erroneously?).
There was a problem hiding this comment.
- Agh, yeah, I forgot about that horribly confusing
plugins/uber/uberthing.
| * *various Sideboard folders* | ||
| * `development.ini`: called sideboard-development.ini in Quickstart, this is a config file for Sideboard. You might use this to control the order in which plugins are loaded. | ||
| * `plugins` | ||
| * `rams` |
There was a problem hiding this comment.
There is no rams directory under plugins.
There was a problem hiding this comment.
There would be if you git clone the upstream RAMS repo in the plugins folder. For the MAGFest install it is called uber.
There was a problem hiding this comment.
It MUST be called uber though, even if you clone the rams repo. If you leave it named rams a bunch of stuff breaks.
| * RAMS Test | ||
| * *various Sideboard folders* | ||
| * `development.ini`: called sideboard-development.ini in Quickstart, this is a config file for Sideboard. You might use this to control the order in which plugins are loaded. | ||
| * `plugins` |
There was a problem hiding this comment.
May want to note here that this directory is mounted from quickstart/src on the host machine during a docker start from the development profile. In the ramsproject/rams Docker image plugins/uber already exists and has the default contents from GitHub for the main uber plugin, but when you start with the developer profile Docker replaces that directory with the quickstart/src directory on your host.
Further note, probably belongs elsewhere in this document: This is a common source of confusion, especially when Docker's file sharing isn't working right and suddenly the plugins directory is empty on the running container as a result. The best way to diagnose if this is the case is to docker exec into a shell on the running container and just do a ls /app/plugins/ from there.
Corrects the name for the repo folder, and adds some extra notes to the structure.
|
OK, I think I fixed stuff @thaeli |
After extensive discussion with someone trying to make RAMS work with their own infrastructure, it's clear that defining how the RAMS + Sideboard app is actually structured would be very helpful to developers. This is kind of a weird place to put it but this readme is the best we've got for decent documentation right now.