Skip to content

Latest commit

 

History

History
139 lines (95 loc) · 5.22 KB

DOCKER.md

File metadata and controls

139 lines (95 loc) · 5.22 KB
Raw

Docker

RESO Certification Utils can be used in a Docker container.

Note: There's currently an issue with ARM 64 platforms and Gradle/Docker. As such, Docker won't work on Apple Silicon. Please install locally instead. See: README.

Docker Installation

To build a Docker container, first install Docker.

Make sure it's running:

$ docker ps -a

If Docker is running, you should see information about any containers on your system.

If you receive a message similar to the following, then Docker is not running:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

Cloning Repository

Make sure Git is installed using the following command in the terminal:

$ git --version

If it's not installed, you'll see some kind of error.

Otherwise, clone the repository:

$ git clone https://github.com/RESOStandards/reso-certification-utils
Cloning into 'reso-certification-utils'...
remote: Enumerating objects: 691, done.
remote: Counting objects: 100% (192/192), done.
remote: Compressing objects: 100% (127/127), done.
remote: Total 691 (delta 101), reused 97 (delta 65), pack-reused 499
Receiving objects: 100% (691/691), 436.98 KiB | 3.24 MiB/s, done.
Resolving deltas: 100% (320/320), done.

Then change to the source directory:

$ cd reso-certification-utils

Building Docker Container

To build the Docker container, use the following command:

$ docker build -t reso-certification-utils --no-cache .

Once the container has been built, it should show up in the list of available containers:

$ docker images
REPOSITORY                                          TAG                      IMAGE ID       CREATED             SIZE
reso-certification-utils                            latest                   262038261764   About an hour ago   1.06GB
...

If there are any errors building the container, try repeating the process.

Running reso-certification-utils

The entrypoint of the Docker container is the reso-certification-utils application, so you can use it for any of the commands in the README.

$ docker run -it reso-certification-utils --help
Usage: RESO Certification Utils [options] [command]

Command line batch-testing and restore utils

Options:
  -V, --version             output the version number
  -h, --help                display help for command

Commands:
  schema [options]          Generate a schema or validate a payload against a schema
  restore [options]         Restores local or S3 results to a RESO Certification API instance
  runDDTests [options]      Runs Data Dictionary tests
  findVariations [options]  Finds possible variations in metadata using a number of methods.
  replicate [options]       Replicates data from a given resource with expansions.
  metadata [options]        Converts metadata from OData XML to RESO Format.
  help [command]            display help for command

Depending on the task, you will also need to mount the appropriate volumes in the Docker container.

RESO Certification

Data Dictionary Testing

To run the Data Dictionary tests, use the following command once the container has been built:

$ docker run -v ./results:/results -v ./config.json:/config.json -it reso-certification-utils runDDTests -v 1.7 -p /config.json -l 200 -a

Where:

  • -v ./results:/results mounts the local results directory to the container, and will create the local directory if it doesn't exist
  • -v ./config.json:/config.json mounts a config file in the current directory to the Docker container. See: sample config
  • -it tells Docker to use an interactive terminal
  • reso-certification-utils is the name of the container to run
  • -v 1.7 uses Data Dictionary 1.7 tests and references
  • -p /config.json is the path to the config file within the container
  • -l 200 sets the limit to 200 records per resource / expansion / strategy (default: 100,000)
  • -a is the option to run all tests - without it, only metadata tests are run

Results will be outputted in a directory called results.

Variations Service

In order to use the Variations Service, the Data Dictionary 2.0 tests will need an environment variable with a token.

The required parameters can be passed into the container using an environment variable file as follows:

$ docker run -v ./results:/results -v ./config.json:/config.json -it --env-file .env reso-certification-utils runDDTests -p /config.json -l 200 -a

See sample.env for a sample .env file.

In this case, you will need additional information to use the Variations Service. Please contact dev@reso.org for more information.

If the auth info isn't present, only machine-matching will be used. This is still enough to get started with DD 2.0 testing.

You can also pass the environment variables in the file directly to the container with the -e flag, but using a file is preferred since it avoids sensitive information being exposed in the command history.

Other Tasks

See the RESO Certification example for how to mount files and directories.