-
Notifications
You must be signed in to change notification settings - Fork 61
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore(readme): update with info about docker image
- Loading branch information
1 parent
f4b22ee
commit 5b3089a
Showing
1 changed file
with
79 additions
and
54 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,7 @@ | ||
| # TopBraid SHACL API | ||
|
|
||
| [](https://github.com/topquadrant/shacl/releases/latest) | ||
|
|
||
| **An open source implementation of the W3C Shapes Constraint Language (SHACL) based on Apache Jena.** | ||
|
|
||
| Contact: Ashley Caselli ([email protected])\ | ||
|
|
@@ -31,9 +33,16 @@ To get started, look at the class ValidationUtil in | |
| the package org.topbraid.shacl.validation. | ||
| There is also an [Example Test Case](../master/src/test/java/org/topbraid/shacl/ValidationExample.java) | ||
|
|
||
| # How to use it | ||
| - [Application dependency](#application-dependency) | ||
| - [Docker](#docker-usage) | ||
| - [Command line](#command-line-usage) | ||
|
|
||
| ## Application dependency | ||
|
|
||
| Releases are available in the central maven repository: | ||
| Releases are available in the [central maven repository](https://mvnrepository.com/artifact/org.topbraid/shacl): | ||
|
|
||
| > :warning: Replace `*VER*` with the actual package version. Consult the package page to find what versions are available. | ||
| ``` | ||
| <dependency> | ||
|
|
@@ -43,71 +52,27 @@ Releases are available in the central maven repository: | |
| </dependency> | ||
| ``` | ||
|
|
||
| ## Command Line Usage | ||
|
|
||
| Download the latest release from: | ||
|
|
||
| `https://repo1.maven.org/maven2/org/topbraid/shacl/` | ||
|
|
||
| The binary distribution is: | ||
|
|
||
| `https://repo1.maven.org/maven2/org/topbraid/shacl/*VER*/shacl-*VER*-bin.zip`. | ||
|
|
||
| Two command line utilities are included: `shaclvalidate` (performs constraint validation) and `shaclinfer` (performs SHACL rule inferencing). | ||
|
|
||
| To use them, set up your environment similar to https://jena.apache.org/documentation/tools/ (note that the SHACL download includes Jena). | ||
|
|
||
| For example, on Windows: | ||
|
|
||
| ``` | ||
| SET SHACLROOT=C:\Users\Holger\Desktop\shacl-1.4.3-bin | ||
| SET PATH=%PATH%;%SHACLROOT%\bin | ||
| ``` | ||
|
|
||
| As another example, for Linux, add to .bashrc these lines: | ||
|
|
||
| ``` | ||
| # for shacl | ||
| export SHACLROOT=/home/holger/shacl/shacl-1.4.3-bin/shacl-1.4.3/bin | ||
| export PATH=$SHACLROOT:$PATH | ||
| ``` | ||
|
|
||
| After setting up the environment, you can run the command line utilities (i.e. validation) using the following command: | ||
|
|
||
| - Windows: `shaclvalidate.bat -datafile myfile.ttl -shapesfile myshapes.ttl` | ||
|
|
||
| - Linux/Unix: `shaclvalidate.sh -datafile myfile.ttl -shapesfile myshapes.ttl` | ||
|
|
||
| Both tools (Windows, Linux) take the parameters described in the [Dockerfile Usage](#dockerfile-usage) section. **Currently, only Turtle (.ttl) files are supported.** | ||
|
|
||
| The tools print the validation report or the inferences graph to the output screen. | ||
| ## Docker Usage | ||
|
|
||
| ## Dockerfile Usage | ||
| You can use the tool as Docker image. Prebuild Docker images are available at the [GitHub Container Registry](https://github.com/ashleycaselli/shacl/pkgs/container/shacl). The SHACL API runs inside the Docker image, with two possible commands available. To run the validator: | ||
|
|
||
| The `Dockerfile` in the `.docker` folder includes a minimal Java Runtime Environment for the SHACL API that clocks in at ~85Mb. To get the latest release of the image use: | ||
|
|
||
| ``` | ||
| docker build -f .docker/Dockerfile -t ghcr.io/topquadrant/shacl:1.4.3 --build-arg VERSION=1.4.3 . | ||
| ``` | ||
| > :warning: It is generally better to use a fixed version of the docker image, rather than the `latest` tag. Consult the package page to find what versions are available. | ||
| To use the Docker image, there are two possible commands. To run the validator: | ||
|
|
||
| ``` | ||
| docker run --rm -v /path/to/data:/data ghcr.io/topquadrant/shacl:1.4.3 validate -datafile /data/myfile.ttl -shapesfile /data/myshapes.ttl | ||
| docker run --rm -v /path/to/data:/data ghcr.io/ashleycaselli/shacl:latest validate -datafile /data/myfile.ttl -shapesfile /data/myshapes.ttl | ||
| ``` | ||
|
|
||
| To run rule inferencing: | ||
|
|
||
| ``` | ||
| docker run --rm -v /path/to/data:/data ghcr.io/topquadrant/shacl:1.4.3 infer -datafile /data/myfile.ttl -shapesfile /data/myshapes.ttl | ||
| docker run --rm -v /path/to/data:/data ghcr.io/ashleycaselli/shacl:latest infer -datafile /data/myfile.ttl -shapesfile /data/myshapes.ttl | ||
| ``` | ||
|
|
||
| Any other command after `ghcr.io/topquadrant/shacl:1.4.3` will print the following help page: | ||
| Any other command after `ghcr.io/ashleycaselli/shacl:latest` will print the following help page: | ||
|
|
||
| ``` | ||
| Please use this docker image as follows: | ||
| docker run -v /path/to/data:/data ghcr.io/topquadrant/shacl:1.4.3 [COMMAND] [PARAMETERS] | ||
| docker run -v /path/to/data:/data ghcr.io/ashleycaselli/shacl:latest [COMMAND] [PARAMETERS] | ||
| COMMAND: | ||
| validate | ||
| to run validation | ||
|
|
@@ -128,14 +93,74 @@ PARAMETERS: | |
| disables the import of external ontologies | ||
| ``` | ||
|
|
||
| ### Build image locally | ||
|
|
||
| You can build your own Docker image locally by using the `Dockerfile` provided in the `.docker` folder. It includes a minimal Java Runtime Environment for the SHACL API that clocks in at ~85Mb. To build it locally use: | ||
|
|
||
| > :warning: If no value for the `ARCH_BASE` variable is provided, the image will be built using the default architecture value (**eclipse-temurin:21-alpine**) | ||
| ``` | ||
| docker build \ | ||
| -f .docker/Dockerfile \ | ||
| -t ghcr.io/topquadrant/shacl:VER \ | ||
| --build-arg VERSION=VER . | ||
| ``` | ||
|
|
||
| If you'd like to build the image locally in an `x86` architecture, use: | ||
|
|
||
| ``` | ||
| docker build -f .docker/Dockerfile -t ghcr.io/topquadrant/shacl:1.4.3 --build-arg VERSION=1.4.3 --build-arg ARCH_BASE=eclipse-temurin:11-alpine . | ||
| docker build | ||
| -f .docker/Dockerfile \ | ||
| -t ghcr.io/topquadrant/shacl:VER \ | ||
| --build-arg VERSION=VER \ | ||
| --build-arg ARCH_BASE=eclipse-temurin:21-alpine . | ||
| ``` | ||
|
|
||
| If your architecture is `arm`, use: | ||
|
|
||
| ``` | ||
| docker build -f .docker/Dockerfile -t ghcr.io/topquadrant/shacl:1.4.3 --build-arg VERSION=1.4.3 --build-arg ARCH_BASE=amazoncorretto:11-alpine3.18-jdk . | ||
| ``` | ||
| docker build \ | ||
| -f .docker/Dockerfile \ | ||
| -t ghcr.io/topquadrant/shacl:VER \ | ||
| --build-arg VERSION=VER \ | ||
| --build-arg ARCH_BASE=amazoncorretto:21-alpine3.20-jdk . | ||
| ``` | ||
|
|
||
| ## Command Line Usage | ||
|
|
||
| Download the latest release from: | ||
|
|
||
| `https://repo1.maven.org/maven2/org/topbraid/shacl/` | ||
|
|
||
| The binary distribution is: | ||
|
|
||
| `https://repo1.maven.org/maven2/org/topbraid/shacl/*VER*/shacl-*VER*-bin.zip`. | ||
|
|
||
| Two command line utilities are included: `shaclvalidate` (performs constraint validation) and `shaclinfer` (performs SHACL rule inferencing). | ||
|
|
||
| To use them, set up your environment similar to https://jena.apache.org/documentation/tools/ (note that the SHACL download includes Jena). | ||
|
|
||
| For example, on Windows: | ||
|
|
||
| ``` | ||
| SET SHACLROOT=C:\Users\Holger\Desktop\shacl-1.4.3-bin | ||
| SET PATH=%PATH%;%SHACLROOT%\bin | ||
| ``` | ||
|
|
||
| As another example, for Linux, add to .bashrc these lines: | ||
|
|
||
| ``` | ||
| # for shacl | ||
| export SHACLROOT=/home/holger/shacl/shacl-1.4.3-bin/shacl-1.4.3/bin | ||
| export PATH=$SHACLROOT:$PATH | ||
| ``` | ||
|
|
||
| After setting up the environment, you can run the command line utilities (i.e. validation) using the following command: | ||
|
|
||
| - Windows: `shaclvalidate.bat -datafile myfile.ttl -shapesfile myshapes.ttl` | ||
|
|
||
| - Linux/Unix: `shaclvalidate.sh -datafile myfile.ttl -shapesfile myshapes.ttl` | ||
|
|
||
| Both tools (Windows, Linux) take the parameters described in the [Docker Usage](#docker-usage) section. **Currently, only Turtle (.ttl) files are supported.** | ||
|
|
||
| The tool print the validation report or the inferences graph to the output screen. | ||