diff --git a/README.rst b/README.rst index d35028e46..3e55b1029 100644 --- a/README.rst +++ b/README.rst @@ -91,7 +91,7 @@ First clone the source code:: Using Docker Compose ---------------------- +~~~~~~~~~~~~~~~~~~~~~~ Please find the docker documentation in `Docker Installation `__ diff --git a/docs/docker_installation.rst b/docs/docker_installation.rst new file mode 100644 index 000000000..ad6782f0d --- /dev/null +++ b/docs/docker_installation.rst @@ -0,0 +1,74 @@ +.. _docker_image: + +Docker image +============ + +Get Docker +---------- + +The first step is to download and install Docker on your platform. +Refer to the following Docker documentation and choose the best installation +path for you: `Get Docker `_ + +Build the Image +--------------- + +VulnerableCode is distributed with ``Dockerfile`` and ``docker-compose.yml`` files +required for the creation of the Docker image. + +Clone the git `VulnerableCode repo `_, +create an environment file, and build the Docker image: + +.. code-block:: bash + + git clone https://github.com/nexB/vulnerablecode.git && cd vulnerablecode + make envfile + docker-compose build + +.. note:: + + The image will need to be re-built when the VulnerableCode app source code is + modified or updated via + ``docker-compose build --no-cache vulnerablecode`` + +Run the Image +------------- + +Run your image as a container + +.. code-block:: bash + + docker-compose up + + +At this point, the VulnerableCode app should be running at port ``8000`` on your Docker host. +Go to http://localhost:8000/ on a web browser to access the web UI. +Optionally, you can set ``NGINX_PORT`` environment variable in your shell or in the `.env` file to run on a different port than 8000. + +.. warning:: + + To access a dockerized VulnerableCode app from a remote location, the ``ALLOWED_HOSTS`` + setting need to be provided in your ``docker.env`` file:: + + ALLOWED_HOSTS=.domain.com,127.0.0.1 + + Refer to `Django ALLOWED_HOSTS settings `_ + for documentation. + + +Invoke the importers +-------------------- + +Connect to the Docker container ``bash``. +From here you can access ``manage.py`` and run management commands +to import data as specified in the Data import section of the `main manual <../README.rst>`_ and run commands +for the importers from there + +For example: + +.. code-block:: bash + + docker-compose exec vulnerablecode bash + ./manage.py import --list + +