Alternative FREEC usage from a container

Dockerfile

@@ -0,0 +1,20 @@
+
+FROM ubuntu:22.04
+
+RUN apt-get update && \
+    apt-get install -y gcc g++ make
+
+COPY src /app/src
+
+WORKDIR /app/src
+
+RUN rm -f /app/src/freec && make && chmod +x /app/src/freec
+
+ARG USER_ID=1000
+ARG GROUP_ID=1000
+
+RUN groupadd --gid $GROUP_ID -r user && useradd -r --uid $USER_ID --gid $GROUP_ID user
+USER user
+
+ENTRYPOINT ["./freec", "-conf"]
+CMD ["/app/data/test/config_BL.txt"]

README.md

@@ -21,7 +21,84 @@ Control-FREEC accepts .GZ files. Support of Eland, BED, SOAP, arachne, psl (BLAT
 
 ---------------------------------------------------------------------------------------------------------------------------
 
-**Installation:** To install FREEC, type "make" in the command line. If you are using Linux 32bit, please remove 64bit-tags from the Makefile file before building the program.
+**Installation:** 
+
+To install FREEC, type "make" in the command line. If you are using Linux 32bit, please remove 64bit-tags from the Makefile file before building the program.
+
+Alternatively, you may experiment with a FREEC executable on any OS, w/o installing make and C++ compiler, by following the steps in the **Using Control-FREEC from a container** section.
+
+***Using Control-FREEC from a container***
+
+You may experiment with FREEC using a [Docker image](https://www.docker.com/resources/what-container/), prepared by the project's development team. By default, the image uses a FREEC executable, compiled from the latest code on the **master** branch. Please see [the list of available versions](https://hub.docker.com/repository/docker/knotnote/control-freec/tags?page=1&ordering=last_updated) in case you want to use another version of FREEC.
+
+1. [Install Docker](https://docs.docker.com/get-docker/).
+2. Get the `knotnote/control-freec:latest` docker image:
+   - if you are using Docker Desktop, follow [these instructions](https://docs.docker.com/desktop/dashboard/#pull-the-latest-image-from-docker-hub)
+   - or from the console: `docker pull knotnote/control-freec:latest`
+3. Get the config file that you plan to use. Modify all file paths to be absolute.
+
+   Example:
+
+         [general]
+         chrLenFile = hs18_chr.len
+
+   becomes:
+
+         [general]
+         chrLenFile = /home/user/data/hs18_chr.len
+
+4. Run FREEC. Use the following command: 
+
+   `docker run --rm -t --mount type=bind,source=abs_path_to_data,target=abs_path_to_data knotnote/control-freec:latest abs_path_to_config_file`
+
+   where:
+
+      - abs_path_to_data - **absolute** path to the directory with input data **and** a configuration file. 
+
+      - abs_path_to_config_file - **absolute** path to the config file.
+
+   The following options are being used:
+
+      - --rm - remove the container after it finishes execution to spare disk space
+
+      - --mount - bind-mount a local directory into the container. The data is **not exposed** to the Internet and stays on the private machine.
+
+   **NOTE.** If your files are located in different folders, you need to add the \'--mount type=bind,source=<path>,target=<path>\' for each folder.
+
+
+   If set up correctly, FREEC outputs will be in the `outputDir` folder, specified in the configuration file.
+
+(optional) 5. Running an interactive experiment.
+
+   If you want to get into the container and modify its contents (for e.g., update the FREEC code and recompile the executable), you may use the following command:
+
+   `docker run -it --name=experiment1 --entrypoint="" --mount type=bind,source=abs_path_to_data,target=abs_path_to_data knotnote/control-freec:latest abs_path_to_config_file bash`
+
+   Here:
+
+   - --name=experiment1 - gives your container a unique name (in case you want to build your own image based on the experiments)
+
+   - '--entrypoint=""' and 'bash' - allows to get into the console inside of the container.
+
+   This could also **be useful** for debugging purposes (validate that data is properly mounted, the code version, etc.)
+
+***Creating a new FREEC container version (for developers)***
+
+From the folder with the Dockerfile, please run the command:
+
+   `docker build -t knotnote/control-freec:<FREEC version> .`
+
+To make the image publicly available:
+
+1. Ensure that you have authenticated to the Dockerhub registry:
+
+   `docker login`
+
+2. Push the image:
+
+   `docker push knotnote/control-freec:<FREEC version>`
+
+Note. To push to the *knotnote/control-freec* Dockerhub repository, please ask collaborators to grant you permissions.
 
 ---------------------------------------------------------------------------------------------------------------------------