Skip to content

Commit 5b3089a

Browse files
ashleycaselliashleycaselli
committed
chore(readme): update with info about docker image
1 parent f4b22ee commit 5b3089a

File tree

1 file changed

+79
-54
lines changed

1 file changed

+79
-54
lines changed

‎README.md‎

Lines changed: 79 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# TopBraid SHACL API
22

3+
[![Latest Release](https://img.shields.io/github/v/release/topquadrant/shacl)](https://github.com/topquadrant/shacl/releases/latest)
4+
35
**An open source implementation of the W3C Shapes Constraint Language (SHACL) based on Apache Jena.**
46

57
Contact: Ashley Caselli ([email protected])\
@@ -31,9 +33,16 @@ To get started, look at the class ValidationUtil in
3133
the package org.topbraid.shacl.validation.
3234
There is also an [Example Test Case](../master/src/test/java/org/topbraid/shacl/ValidationExample.java)
3335

36+
# How to use it
37+
- [Application dependency](#application-dependency)
38+
- [Docker](#docker-usage)
39+
- [Command line](#command-line-usage)
40+
3441
## Application dependency
3542

36-
Releases are available in the central maven repository:
43+
Releases are available in the [central maven repository](https://mvnrepository.com/artifact/org.topbraid/shacl):
44+
45+
> :warning: Replace `*VER*` with the actual package version. Consult the package page to find what versions are available.
3746
3847
```
3948
<dependency>
@@ -43,71 +52,27 @@ Releases are available in the central maven repository:
4352
</dependency>
4453
```
4554

46-
## Command Line Usage
47-
48-
Download the latest release from:
49-
50-
`https://repo1.maven.org/maven2/org/topbraid/shacl/`
51-
52-
The binary distribution is:
53-
54-
`https://repo1.maven.org/maven2/org/topbraid/shacl/*VER*/shacl-*VER*-bin.zip`.
55-
56-
Two command line utilities are included: `shaclvalidate` (performs constraint validation) and `shaclinfer` (performs SHACL rule inferencing).
57-
58-
To use them, set up your environment similar to https://jena.apache.org/documentation/tools/ (note that the SHACL download includes Jena).
59-
60-
For example, on Windows:
61-
62-
```
63-
SET SHACLROOT=C:\Users\Holger\Desktop\shacl-1.4.3-bin
64-
SET PATH=%PATH%;%SHACLROOT%\bin
65-
```
66-
67-
As another example, for Linux, add to .bashrc these lines:
68-
69-
```
70-
# for shacl
71-
export SHACLROOT=/home/holger/shacl/shacl-1.4.3-bin/shacl-1.4.3/bin
72-
export PATH=$SHACLROOT:$PATH
73-
```
74-
75-
After setting up the environment, you can run the command line utilities (i.e. validation) using the following command:
76-
77-
- Windows: `shaclvalidate.bat -datafile myfile.ttl -shapesfile myshapes.ttl`
78-
79-
- Linux/Unix: `shaclvalidate.sh -datafile myfile.ttl -shapesfile myshapes.ttl`
80-
81-
Both tools (Windows, Linux) take the parameters described in the [Dockerfile Usage](#dockerfile-usage) section. **Currently, only Turtle (.ttl) files are supported.**
82-
83-
The tools print the validation report or the inferences graph to the output screen.
55+
## Docker Usage
8456

85-
## Dockerfile Usage
57+
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:
8658

87-
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:
88-
89-
```
90-
docker build -f .docker/Dockerfile -t ghcr.io/topquadrant/shacl:1.4.3 --build-arg VERSION=1.4.3 .
91-
```
9259
> :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.
9360
94-
To use the Docker image, there are two possible commands. To run the validator:
95-
9661
```
97-
docker run --rm -v /path/to/data:/data ghcr.io/topquadrant/shacl:1.4.3 validate -datafile /data/myfile.ttl -shapesfile /data/myshapes.ttl
62+
docker run --rm -v /path/to/data:/data ghcr.io/ashleycaselli/shacl:latest validate -datafile /data/myfile.ttl -shapesfile /data/myshapes.ttl
9863
```
9964

10065
To run rule inferencing:
10166

10267
```
103-
docker run --rm -v /path/to/data:/data ghcr.io/topquadrant/shacl:1.4.3 infer -datafile /data/myfile.ttl -shapesfile /data/myshapes.ttl
68+
docker run --rm -v /path/to/data:/data ghcr.io/ashleycaselli/shacl:latest infer -datafile /data/myfile.ttl -shapesfile /data/myshapes.ttl
10469
```
10570

106-
Any other command after `ghcr.io/topquadrant/shacl:1.4.3` will print the following help page:
71+
Any other command after `ghcr.io/ashleycaselli/shacl:latest` will print the following help page:
10772

10873
```
10974
Please use this docker image as follows:
110-
docker run -v /path/to/data:/data ghcr.io/topquadrant/shacl:1.4.3 [COMMAND] [PARAMETERS]
75+
docker run -v /path/to/data:/data ghcr.io/ashleycaselli/shacl:latest [COMMAND] [PARAMETERS]
11176
COMMAND:
11277
validate
11378
to run validation
@@ -128,14 +93,74 @@ PARAMETERS:
12893
disables the import of external ontologies
12994
```
13095

96+
### Build image locally
97+
98+
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:
99+
100+
> :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**)
101+
102+
```
103+
docker build \
104+
-f .docker/Dockerfile \
105+
-t ghcr.io/topquadrant/shacl:VER \
106+
--build-arg VERSION=VER .
107+
```
108+
131109
If you'd like to build the image locally in an `x86` architecture, use:
132110

133111
```
134-
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 .
112+
docker build
113+
-f .docker/Dockerfile \
114+
-t ghcr.io/topquadrant/shacl:VER \
115+
--build-arg VERSION=VER \
116+
--build-arg ARCH_BASE=eclipse-temurin:21-alpine .
135117
```
136118

137119
If your architecture is `arm`, use:
138120

139121
```
140-
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 .
141-
```
122+
docker build \
123+
-f .docker/Dockerfile \
124+
-t ghcr.io/topquadrant/shacl:VER \
125+
--build-arg VERSION=VER \
126+
--build-arg ARCH_BASE=amazoncorretto:21-alpine3.20-jdk .
127+
```
128+
129+
## Command Line Usage
130+
131+
Download the latest release from:
132+
133+
`https://repo1.maven.org/maven2/org/topbraid/shacl/`
134+
135+
The binary distribution is:
136+
137+
`https://repo1.maven.org/maven2/org/topbraid/shacl/*VER*/shacl-*VER*-bin.zip`.
138+
139+
Two command line utilities are included: `shaclvalidate` (performs constraint validation) and `shaclinfer` (performs SHACL rule inferencing).
140+
141+
To use them, set up your environment similar to https://jena.apache.org/documentation/tools/ (note that the SHACL download includes Jena).
142+
143+
For example, on Windows:
144+
145+
```
146+
SET SHACLROOT=C:\Users\Holger\Desktop\shacl-1.4.3-bin
147+
SET PATH=%PATH%;%SHACLROOT%\bin
148+
```
149+
150+
As another example, for Linux, add to .bashrc these lines:
151+
152+
```
153+
# for shacl
154+
export SHACLROOT=/home/holger/shacl/shacl-1.4.3-bin/shacl-1.4.3/bin
155+
export PATH=$SHACLROOT:$PATH
156+
```
157+
158+
After setting up the environment, you can run the command line utilities (i.e. validation) using the following command:
159+
160+
- Windows: `shaclvalidate.bat -datafile myfile.ttl -shapesfile myshapes.ttl`
161+
162+
- Linux/Unix: `shaclvalidate.sh -datafile myfile.ttl -shapesfile myshapes.ttl`
163+
164+
Both tools (Windows, Linux) take the parameters described in the [Docker Usage](#docker-usage) section. **Currently, only Turtle (.ttl) files are supported.**
165+
166+
The tool print the validation report or the inferences graph to the output screen.

0 commit comments

Comments
 (0)