diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..3d31069 --- /dev/null +++ b/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"] \ No newline at end of file diff --git a/README.md b/README.md index f8ceb97..bd5db40 100644 --- a/README.md +++ b/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=,target=\' 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: .` + +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:` + +Note. To push to the *knotnote/control-freec* Dockerhub repository, please ask collaborators to grant you permissions. ---------------------------------------------------------------------------------------------------------------------------