Commit 3f6025f5 authored by Caillat Michel's avatar Caillat Michel
Browse files

Update README.md

parent de3238b6
......@@ -9,11 +9,11 @@ After an initial phase where the project was built as a set of applications runn
those applications in a Docker container mostly to ease the distribution and the installation of the product.
## Architecture
The facility is architectured as a composition of two docker :
The facility is architectured as a composition of two Docker images :
* `yafitsv` : an HTTP server (NodeJS) that reacts to the user's requests such that navigating in the FITS collection or visually exploring the content of one selected FITS file.
* `yafitss` : an HTTP server (Python+Bottle) which actually performs all the hard work with FITS files ( browsing, loading in memory, extract parts to display, etc...) and is callable via a serie of REST APIs
The relations between the user's WEB browser and the servers `yafitss` and `yafitsv` can be depicted as follows :
The relations between the user's WEB browser and the containerized servers `yafitss` and `yafitsv` can be depicted as follows :
<pre>
YAFITS containers composition
......@@ -28,59 +28,80 @@ The relations between the user's WEB browser and the servers `yafitss` and `yafi
</pre>
## Building the images composition
## Requirements
Have the applications `docker` (https://docs.docker.com/install/) and `docker-compose` (https://docs.docker.com/compose/install/) available on the host where you plan to deploy the project.
Even if it's a not a requirement, having the Docker management and monitoring tool `portainer` (https://www.portainer.io/) installed is indiscutably a bonus.
## Getting the source code
Clone of the project.
## Adapting the configuration file
`yafits` is designed to be easily shared and deployed on a platform where the docker and docker-compose applications are available after having defined a couple of environment variables.
Prior to any other action :
* Set the directory's project as the current directory :
`cd <..>/yafits`
* Launch the build command :
* Copy the configuration file template `.yafits.bashrc.dist` to a location and a name of your choice (e.g. `$HOME/.yafits.bashrc`) and edit its content accordingly with your local environment.
* Execute the edited configuration file (e.g. `. $HOME/.yafits.bashrc`)
`docker-compose build
Note that the choice of the tag assigned to the image is left to the choice of the installer. Any other valid name than `yafits_1` can chosen.
## Building the images composition
* Launch the build command : it'll take some time due to the CENTOS base and Anaconda installations.
`docker-compose build`
## Running the image in container
The command given below has some parts which must used verbatim while others can be changed following the host specificities and the installer's preferences.
## Running the images compositions in containers
`
docker run --name yafits_1 -p4250:4250 -v"/obs/partemix/dckr/yafitss/log:/home/partemix/log" -v"/datartemix/ALMA:/home/partemix/dataroot" yafits_1
docker-compose up -d
`
where :
* `yafits_1` after the `--name` option is the name given to the container. It can be freely adapted by the installer.
* `4250:4250`after the `-p` option defines the mapping between the internal and exposed container's port (after the `:`) and the host's port ( before the `:`). The first value, that is the host's port can be changed by the installer.
* `/obs/partemix/dckr/yafitss/log:/home/partemix/log` after the `-v` option : a bind mount of the host directory `/obs/partemix/dckr/yafitss/log` is performed on the container directory `/home/partemix/log`. This mount defines where the log files will be written on the host filesystem. Again the host directory can be adjusted by the installer. ( See **Files considerations** )
* `/datartemix/ALMA:/home/partemix/dataroot` after the `-v` option : a bind mount of the host directory `/datartemix/ALMA` the container's directory `/home/partemix/dataroot`. This mount defines where FITS files will be read and where the PNG files will be written on the filesystem. Again the host directory can be adjusted by the installer. ( See **Data Files organization** and **Files considerations** )
## Account considerations.
Two containers should be running ready to process your requests at `http://${YAFITSV_HOST}:${YAFITSV:PORT}/browse`
( the two env variables are the ones you have defined in the configuration script. You will very likely use their value instead of their
names as above. E.g. `http://juliette.obspm.fr:3022/` )
## Technical details
The informations below are given for the curious of technical details. They may be useful in case of problems, but normally reading this
section is not required.
### Account considerations.
Instead of leaving the default account (root, uid==0) running the code, one uses a specific account created during the image build. Its name is `partemix` with uid==1000, gid==1001.
## Data files organization.
### Data files organization.
Data files are on the one hand the FITS files (readonly) and on the other hand the PNG files (read/write). The software expects to find these files respectively in a `FITS`
directory and in a `PNG` directory both subdirectories of a same toplevel directory. The table below depicts the situation of the example of the `docker run`command ( see above)
where the host directory `/datartemix/datartemix` with its two subdirectories `FITS` and `PNG` is mounted on the container's directory `/home/partemix/dataroot` .
Exemple :
|host|container|
|:----|:----|
| /datartemix/ALMA |/home/partemix/dataroot |
| /datartemix/ALMA/FITS , /datartemix/ALMA/PNG | /home/partemix/FITS , /home/partemix/PNG |
| /datartemix/ALMA/FITS , /tmp/PNG | /home/partemix/FITS , /home/partemix/PNG |
## Files considerations.
### Files considerations.
A characteristic of the container is that **all** the data that it accesses to are residing on the host filesystem. The container has NO data on his own; in other words all the data are persistent. A particular attention must therefore be paid to the protections defined on the data and the permissions to be set up for the applications executed by the container have the necessary access to them.
The informations given below are pertinent with the assumption that the image has been built with the Dockerfile left unchanged.
### FITS files.
#### FITS files.
The FITS files which are the _raw material_ of yafits are accessed to as a readonly resource of the host filesystem. The most permissive way to ensure their readability
by the container is to make them readable by anyone (`chmod a+r`). A less permissive approach is to allow them to be read by the group gid==1001 and to put their owner into that group, possibly at the cost of creating such a group. The most restrictive access would be to have a user with uid==1000 ( which is not always possible ) and the FITS files belonging to that user.
### PNG files.
#### PNG files.
The PNG files are temporary files generated on the fly for the visualization of FITS files contents. Consequently the directory used as a repository for these files must be writable by (uid==1000,gid==1001). As for the FITS files one can
choose between the three options 1) writable by anyone 2) writable by group==1001 with the PNG directory's owner in that group and 3) the PNG directory belonging to uid==1000 and writable by the owner.
### LOG files.
#### LOG files.
Both servers `yafitsv` and `yafitss` generates log files in a directory of the host which must be writable by uid=1000,gid=1001. Again one can use one of the strategies presented above for the PNG and FITS files.
\ No newline at end of file
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment