diff --git a/README.md b/README.md index ce1eb1c8..5a675cac 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,6 @@ Tern gives you a deeper understanding of your container's bill of materials so y ![Tern quick demo](/docs/img/tern_demo_fast.gif) - # Getting Started ## GitHub Action @@ -70,13 +69,16 @@ If you have a Linux OS you will need a distro with a kernel version >= 4.0 (Ubun - Python 3.6 or newer (sudo apt-get install python3.6(3.7) or sudo dnf install python36(37)) - Pip (sudo apt-get install python3-pip). - jq (sudo apt-get install jq or sudo dnf install jq) +- skopeo (See [here](https://github.com/containers/skopeo/blob/main/install.md) for installation instructions or building from source) -Some distro versions have all of these except `attr` and/or `jq` preinstalled but both are common utilities and are available via the package manager. +Some distro versions have all of these except `attr`, `jq`, and/or `skopeo` preinstalled. `attr` and `jq` are common utilities and are available via the package manager. `skopeo` has only recently been packages for common Linux distros. If you don't see your distro in the list, your best bet is building from source, which is reasonably straightforward if you have Go installed. -For Docker containers +For analyzing Dockerfiles and to use the "lock" function - Docker CE (Installation instructions can be found here: https://docs.docker.com/engine/installation/#server) -Make sure the docker daemon is running. +*NOTE:* We do not provide advise on the usage of [Docker Desktop](https://www.docker.com/blog/updating-product-subscriptions/) + +Once installed, make sure the docker daemon is running. Create a python3 virtual environment: ``` @@ -103,7 +105,7 @@ $ tern report -o output.txt -i debian:buster ``` ## Getting Started with Docker -Docker is the most widely used tool to build and run containers. If you already have Docker installed, you can run Tern by building a container with the Dockerfile provided and the `docker_run.sh` script: +Docker is the most widely used tool to build and run containers. If you already have Docker installed, you can run Tern by building a container with the Dockerfile provided. Clone this repository: ``` @@ -132,7 +134,13 @@ $ docker build -f ci/Dockerfile -t ternd . +ENTRYPOINT ["tern", "-q"] ``` -Run the script `docker_run.sh`. You may need to use sudo. In the below command `debian` is the docker hub container image name and `buster` is the tag that identifies the version we are interested in analyzing. +Run the ternd container image + +``` +$ docker run --rm ternd report -i debian:buster +``` + +If you are using this container to analyze Dockerfiles and to use the "lock" feature, then you must volume mount the docker socket. We have a convenience script which will do that for you. ``` $ ./docker_run.sh ternd "report -i debian:buster" > output.txt @@ -143,15 +151,16 @@ To produce a json report run $ ./docker_run.sh ternd "report -f json -i debian:buster" ``` -What the `docker_run.sh` script does is run the built container. - Tern is not distributed as Docker images yet. This is coming soon. Watch the [Project Status](#project-status) for updates. **WARNING**: If using the `--driver fuse` or `--driver overlay2` storage driver options, then the docker image needs to run as privileged. + ``` -docker run --privileged -v /var/run/docker.sock:/var/run/docker.sock ternd "--driver fuse report -i debian:buster" +docker run --privileged -v /var/run/docker.sock:/var/run/docker.sock ternd --driver fuse report -i debian:buster ``` +You can make this change to the `docker_run.sh` script to make it easier. + ## Getting Started with Vagrant Vagrant is a tool to setup an isolated virtual software development environment. If you are using Windows or Mac OSes and want to run Tern from the command line (not in a Docker container) this is the best way to get started as Tern does not run natively in a Mac OS or Windows environment at this time. diff --git a/ci/Dockerfile b/ci/Dockerfile index 454fb831..57b3f478 100644 --- a/ci/Dockerfile +++ b/ci/Dockerfile @@ -24,6 +24,7 @@ RUN echo "deb http://deb.debian.org/debian bullseye main" > /etc/apt/sources.lis fuse3/bullseye \ git \ jq \ + skopeo \ && rm -rf /var/lib/apt/lists/* COPY --from=builder /install /usr/local diff --git a/ci/test_files_touched.py b/ci/test_files_touched.py index 435ec397..3f0c9ace 100644 --- a/ci/test_files_touched.py +++ b/ci/test_files_touched.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# Copyright (c) 2019-2020 VMware, Inc. All Rights Reserved. +# Copyright (c) 2019-2021 VMware, Inc. All Rights Reserved. # SPDX-License-Identifier: BSD-2-Clause from git import Repo diff --git a/vagrant/Vagrantfile b/vagrant/Vagrantfile index e14563f8..888ab345 100644 --- a/vagrant/Vagrantfile +++ b/vagrant/Vagrantfile @@ -21,7 +21,7 @@ Vagrant.configure("2") do |config| # Every Vagrant development environment requires a box. You can search for # boxes at https://vagrantcloud.com/search. - config.vm.box = "generic/ubuntu1804" + config.vm.box = "generic/ubuntu2004" config.vm.provision :shell, path: "bootstrap.sh" config.vm.synced_folder '.', '/vagrant', disabled: true diff --git a/vagrant/bootstrap.sh b/vagrant/bootstrap.sh index 8a468e7b..9add95cd 100755 --- a/vagrant/bootstrap.sh +++ b/vagrant/bootstrap.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash # -# Copyright (c) 2018-2019 VMware, Inc. All Rights Reserved. +# Copyright (c) 2018-2021 VMware, Inc. All Rights Reserved. # SPDX-License-Identifier: BSD-2-Clause # Update the Ubuntu repositories @@ -10,7 +10,14 @@ sudo apt-get update sudo apt-get -y upgrade # Python3 versions and system dependencies -sudo apt-get install -y python3 python3-pip python3-venv attr +sudo apt-get install -y python3 python3-pip python3-venv attr jq + +# Install skopeo for Ubuntu 20.04 +echo "deb https://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/stable/xUbuntu_20.04/ /" | sudo tee /etc/apt/sources.list.d/devel:kubic:libcontainers:stable.list +curl -L https://download.opensuse.org/repositories/devel:/kubic:/libcontainers:/stable/xUbuntu_20.04/Release.key | sudo apt-key add - +sudo apt-get update +sudo apt-get -y upgrade +sudo apt-get -y install skopeo # Install Docker sudo apt-get install -y docker.io