Merge pull request #236 from crocs-muni/feat/docs-better-install-inst…

…ructions

better docker instructions

Dockerfile

@@ -2,6 +2,7 @@ FROM ubuntu:jammy-20220428
 
 ENV USER="user"
 ENV NB_UID=1000
+ENV NB_GID=1000
 ENV HOME /home/${USER}
 
 #installing dependencies
@@ -19,12 +20,15 @@ RUN apt-get install libqpdf-dev -y
 RUN apt-get install default-jdk -y
 RUN apt-get install graphviz -y
 
+
+RUN groupadd -g ${NB_GID} -o ${USER}
 RUN adduser --disabled-password \
   --gecos "Default user" \
   --uid ${NB_UID} \
+  --gid ${NB_GID} \
   ${USER}
 
-RUN chown -R ${NB_UID} ${HOME}
+RUN chown -R ${NB_UID}:${NB_GID} ${HOME}
 USER ${USER}
 WORKDIR ${HOME}
 

docs/installation.md

@@ -7,6 +7,7 @@ The tool can be installed from PyPi with
 
 ```bash
 pip install -U sec-certs
+python3 -m spacy download en_core_web_sm
 ```
 
 Note, that `Python>=3.8` is required.
@@ -27,9 +28,11 @@ docker pull seccerts/sec-certs
 The stable release is also published on [GitHub](https://github.com/crocs-muni/sec-certs/releases) from where it can be setup for development with
 
 ```bash
+git clone https://github.com/crocs-muni/sec-certs.git
 python3 -m venv venv
 source venv/bin/activate
 pip install -e .
+python3 -m spacy download en_core_web_sm
 ```
 
 Alternatively, our Our [Dockerfile](https://github.com/crocs-muni/sec-certs/blob/main/Dockerfile) represents a reproducible way of setting up the environment.

docs/quickstart.md

@@ -4,7 +4,7 @@
 
 :::{tab-item} Common Criteria
 1. Install the latest version with `pip install -U sec-certs` (see [installation](installation.md)).
-2. Use
+2. In your Python interpreter, type
 ```python
 from sec_certs.dataset import CCDataset
 
@@ -17,7 +17,7 @@ to obtain to obtain freshly processed dataset from [seccerts.org](https://seccer
 
 :::{tab-item} FIPS 140
 1. Install the latest version with `pip install -U sec-certs` (see [installation](installation.md)).
-2. Use
+2. In your Python interpreter, type
 ```python
 from sec_certs.dataset import FIPSDataset
 
@@ -51,6 +51,27 @@ $ fips-certs new-run
 
 This script takes a long time to run (few hours) and will create `./cc_dset` or `./fips_dset` directory. To see all options, call the entrypoint with `--help`.
 
-:::{hint}
-If you installed the docker image, use `docker run -it sec-certs bash` to run the container interactively.
-:::
+## Run sec-certs from docker
+
+If you installed the docker image (see [installation](installation.md)), use `docker run -it sec-certs` to run the container interactively. From there, you can run the `cc-certs` CLI or `fips-certs` CLI. Alternatively, you can serve a Jupyter notebook from the docker to use at your host machine and even write your scripts to some shared folder. Example of both use-cases follow.
+
+### Persistent files with docker mounts
+
+It may be handy to create a shared folder between your host machine and the docker image, especially for the artifacts of sec-certs analysis. This can be achieved either by [docker volumes](https://docs.docker.com/storage/volumes/) or [docker bind mounts](https://docs.docker.com/storage/bind-mounts/). An example follows that achieves a shared folder writable from the container.
+
+```bash
+mkdir seccerts-data && \
+docker run -it --mount type=bind,source="$(pwd)"/seccerts-data/,target=/home/user/data seccerts/sec-certs
+```
+
+The folder should be accessible on your machine on `./seccerts-data` path; from docker on `/home/user/data` path.
+
+### Run jupyter notebook with sec-certs from Docker
+
+You can also use our docker image to serve `jupyter notebook` instance that you can access from your device. Run
+
+```bash
+docker run --rm -it -p 8888:8888 seccerts/sec-certs jupyter notebook --no-browser --ip 0.0.0.0 --NotebookApp.token='' --notebook-dir="/home/user/"
+```
+
+Now, you should be able to access the notebook at `localhost:8888` from your machine. Navigate to `/home/user/sec-certs/notebooks/examples` to see some example notebooks.