Installation Guide
Prerequisites
Installations of
wget
orcurl
andbash
must be available onPATH
.Macaron has been tested with
bash 5.1.16(1)-release
.
Docker (or docker equivalent for your host OS) must be installed, with a docker command line equivalent to Docker 17.06 (Oracle Container Runtime 19.03) and the user should be a member of the operating system group
docker
(to run Docker in rootless mode).We only support
amd64
/x86_64
platforms at the moment.
Download
Macaron is currently distributed as a Docker image. We provide a bash script run_macaron.sh
to easily download and run it.
Note
When run, Macaron will create output files inside the current directory where run_macaron.sh
is run. If you run Docker Desktop, please make sure that the current directory is bind mountable for Docker (see the File Sharing settings).
Download the run_macaron.sh
script and make it executable by running the commands (replace tag
with the version you want or main
for the latest version):
curl -O https://raw.githubusercontent.com/oracle/macaron/<tag>/scripts/release_scripts/run_macaron.sh
chmod +x run_macaron.sh
Verify that the installation is complete
To verify your setup, go to the directory containing the downloaded run_macaron.sh
script and run this command in order to print out the help message for Macaron:
./run_macaron.sh --help
Note
In the first execution, this script will download the Macaron Docker image from ghcr.io/oracle/macaron
which can take some time. However, the next time you run it, the docker image available on your local host will be used.
Note
By default, latest
is used as the tag for the downloaded image. You can choose a specific tag by assigning the environment variable MACARON_IMAGE_TAG
. For example to run Macaron v0.1.0 run: MACARON_IMAGE_TAG=v0.1.0 ./run_macaron.sh --help
Note
By default, the script will always check the docker registry to ensure the docker image is up-to-date. This can be overridden if necessary (e.g. if running offline with a pre-installed image) by assigning the environment variable DOCKER_PULL
. For example: DOCKER_PULL=never ./run_macaron.sh --help
Prepare GitHub access token
A GitHub access token is always required when using the analyze command (see example below) of Macaron as it may query information from GitHub API about public repositories. More information on this analyze command is can be found in Using Macaron.
./run_macaron.sh analyze <rest_of_arguments>
To obtain a GitHub access token, please see the official instructions here.
Ideally, the GitHub token must have read permissions for the repositories that you want to analyze:
Every fine-grained personal-access token should have read permission to public GitHub repositories. However, if you are analyzing a private repository, please select it in the
Repository Access section
.For classic personal-access token, the
repo.public_repo
scope must be selected. Please select the wholerepo
scope if you are running the analysis against private repositories.
After generating a GitHub personal-access token, please store its value in an environment variable called GITHUB_TOKEN
. This environment variable will be read by Macaron for its analyze command.
Now that you have successfully downloaded and installed Macaron, please refer to Using Macaron for the instructions on how to use Macaron.
Proxy Configuration
Make sure your system proxy is correctly set. These environment variables are read from the host machine and set in the Macaron container automatically.
$ export {http,https,ftp}_proxy=http://www-example-proxy:80
$ export no_proxy=localhost,127.0.0.1
In order to connect to the registry on behalf of the Docker client, the Docker daemon service needs the proxies in order to download images:
[Service]
Environment="HTTP_PROXY=http://wwww-example-proxy:80/"
Environment="http_proxy=http://www-example-proxy:80/"
Environment="HTTPS_PROXY=http://www-example-proxy:80/"
Environment="https_proxy=http://www-example-proxy:80/"
The line below shows an example to exclude the proxy intercept:
Environment="NO_PROXY=localhost,127.0.0.1"
Note
If you update /etc/systemd/system/docker.service.d/http-proxy.conf
, you need to reload the daemon and restart the docker service to apply changes.
sudo systemctl daemon-reload
sudo systemctl restart docker.service
You can run the following command to make sure the proxy settings are updated:
sudo systemctl show --property=Environment docker
Maven and Gradle proxy settings
Maven and Gradle do not use the system proxy settings. If the target software component (repository) is using either of these build tools, make sure to set up the following environment variables:
export MAVEN_OPTS="-Dhttp.proxyHost=wwww-example-proxy -Dhttp.proxyPort=80 -Dhttps.proxyHost=wwww-example-proxy -Dhttps.proxyPort=80"
export GRADLE_OPTS="-Dhttp.proxyHost=wwww-example-proxy -Dhttp.proxyPort=80 -Dhttps.proxyHost=wwww-example-proxy -Dhttps.proxyPort=80"
In addition, Macaron uses the global settings files for Maven and Gradle if present on the host machine and copies them to the Docker container. You can set up your proxy settings in the following files:
~/.m2/settings.xml
~/.gradle/gradle.properties
See the Maven and Gradle documentations for more information on setting up proxies.