|
1 | 1 | # ontologies |
| 2 | + |
2 | 3 | A collection of ontologies developed by VAIMEE, integrating classes and properties from well-known ontologies to ensure interoperability and alignment with existing standards. |
| 4 | + |
| 5 | +## Requirements |
| 6 | + |
| 7 | +- Node.js 20 or newer for local HTML generation. |
| 8 | +- npm for installing the renderer dependencies. |
| 9 | +- Docker for building and running the nginx container locally. |
| 10 | +- A GitHub repository with GitHub Actions enabled for CI/CD publishing to Docker Hub. |
| 11 | + |
| 12 | +## Ontology Requirements |
| 13 | + |
| 14 | +The renderer discovers ontology sources automatically from first-level ontology folders such as `agora/`, `jsap/`, `msg/`, `users/`, and `fsm/`. |
| 15 | + |
| 16 | +Each ontology source should: |
| 17 | + |
| 18 | +- Use Turtle-compatible syntax and have a `.ttl` or `.owl` extension. |
| 19 | +- Declare one ontology resource with `rdf:type owl:Ontology` or `a owl:Ontology`. |
| 20 | +- Define classes as `owl:Class` and properties as `owl:ObjectProperty` or `owl:DatatypeProperty`. |
| 21 | +- Prefer `rdfs:label` and `rdfs:comment` on classes and properties so the generated documentation has readable names and descriptions. |
| 22 | +- Prefer ontology-level metadata: `owl:title`, `dct:abstract`, and `dct:description`. |
| 23 | + |
| 24 | +If ontology-level title, abstract, or description metadata is missing, the renderer adds fallback metadata in memory while generating HTML. The source ontology file is not modified. |
| 25 | + |
| 26 | +## Generate HTML Documentation |
| 27 | + |
| 28 | +Install dependencies once: |
| 29 | + |
| 30 | +```sh |
| 31 | +npm install --prefix rdf2html |
| 32 | +``` |
| 33 | + |
| 34 | +Generate all ontology pages and the landing page: |
| 35 | + |
| 36 | +```sh |
| 37 | +npm run --prefix rdf2html build |
| 38 | +``` |
| 39 | + |
| 40 | +The build writes generated HTML beside each ontology source and creates a `public/` directory ready to be served by nginx. The landing page uses `public/ICON_VAIMEE.svg`, `#10B1D8`, and `#0F3E65`. |
| 41 | + |
| 42 | +## Build Locally |
| 43 | + |
| 44 | +Build the nginx image: |
| 45 | + |
| 46 | +```sh |
| 47 | +docker build -t ontologies . |
| 48 | +``` |
| 49 | + |
| 50 | +Run it locally: |
| 51 | + |
| 52 | +```sh |
| 53 | +docker run --rm -p 8080:80 ontologies |
| 54 | +``` |
| 55 | + |
| 56 | +Open `http://localhost:8080` to browse the generated ontology documentation. |
| 57 | + |
| 58 | +## Deploy With CI/CD |
| 59 | + |
| 60 | +The workflow in `.github/workflows/publish.yml` builds the Docker image and publishes it to Docker Hub. |
| 61 | + |
| 62 | +It runs automatically on pushes to `main` or `master`, and can also be started manually from the GitHub Actions tab. |
| 63 | + |
| 64 | +### Configure Docker Hub |
| 65 | + |
| 66 | +Create a Docker Hub repository before publishing the image. For example, create `lroffia/ontologies` from the Docker Hub web interface. |
| 67 | + |
| 68 | +Create a Docker Hub access token from Docker Hub account settings. Use this token for automation instead of your account password. |
| 69 | + |
| 70 | +Configure these GitHub repository settings before running the workflow: |
| 71 | + |
| 72 | +- Secret `DOCKERHUB_USERNAME`: your Docker Hub username. |
| 73 | +- Secret `DOCKERHUB_TOKEN`: a Docker Hub access token. Use an access token instead of your account password. |
| 74 | +- Variable `DOCKERHUB_REPOSITORY`: the Docker Hub image name, for example `lroffia/ontologies`. |
| 75 | + |
| 76 | +### Publish From GitHub Actions |
| 77 | + |
| 78 | +After configuring the repository settings, push to `main` or `master`: |
| 79 | + |
| 80 | +```sh |
| 81 | +git push origin main |
| 82 | +``` |
| 83 | + |
| 84 | +Or start the `Publish ontologies` workflow manually from the GitHub Actions tab. |
| 85 | + |
| 86 | +The workflow builds the Docker image from `Dockerfile`, regenerates the ontology HTML during the Docker build, and pushes the image to Docker Hub. |
| 87 | + |
| 88 | +The published image is tagged as: |
| 89 | + |
| 90 | +- `<dockerhub-repository>:latest` for the default branch. |
| 91 | +- `<dockerhub-repository>:<branch>` for branch builds. |
| 92 | +- `<dockerhub-repository>:sha-<commit>` for immutable commit builds. |
| 93 | + |
| 94 | +### Publish Manually |
| 95 | + |
| 96 | +To build and push the image from your local machine: |
| 97 | + |
| 98 | +```sh |
| 99 | +docker login -u <dockerhub-username> |
| 100 | +docker build -t <dockerhub-repository>:latest . |
| 101 | +docker push <dockerhub-repository>:latest |
| 102 | +``` |
| 103 | + |
| 104 | +For example: |
| 105 | + |
| 106 | +```sh |
| 107 | +docker login -u lroffia |
| 108 | +docker build -t lroffia/ontologies:latest . |
| 109 | +docker push lroffia/ontologies:latest |
| 110 | +``` |
| 111 | + |
| 112 | +Use a Docker Hub access token when Docker asks for the password. |
| 113 | + |
| 114 | +### Build Multi-Architecture Images On macOS |
| 115 | + |
| 116 | +Docker Desktop for macOS includes Buildx. Use it to build images for both Apple Silicon and Linux AMD64 servers. |
| 117 | + |
| 118 | +Create and select a Buildx builder: |
| 119 | + |
| 120 | +```sh |
| 121 | +docker buildx create --name ontologies-builder --use |
| 122 | +docker buildx inspect --bootstrap |
| 123 | +``` |
| 124 | + |
| 125 | +Build and push a multi-architecture image to Docker Hub: |
| 126 | + |
| 127 | +```sh |
| 128 | +docker login -u <dockerhub-username> |
| 129 | +docker buildx build \ |
| 130 | + --platform linux/amd64,linux/arm64 \ |
| 131 | + -t <dockerhub-repository>:latest \ |
| 132 | + --push \ |
| 133 | + . |
| 134 | +``` |
| 135 | + |
| 136 | +For example: |
| 137 | + |
| 138 | +```sh |
| 139 | +docker login -u lroffia |
| 140 | +docker buildx build \ |
| 141 | + --platform linux/amd64,linux/arm64 \ |
| 142 | + -t lroffia/ontologies:latest \ |
| 143 | + --push \ |
| 144 | + . |
| 145 | +``` |
| 146 | + |
| 147 | +Use `--push` for multi-architecture images. Docker cannot load a multi-platform manifest into the local Docker image store with `--load`. |
| 148 | + |
| 149 | +To build only for the current Mac architecture and load it locally: |
| 150 | + |
| 151 | +```sh |
| 152 | +docker buildx build --platform linux/arm64 -t ontologies:local --load . |
| 153 | +``` |
| 154 | + |
| 155 | +To build an AMD64 image on Apple Silicon and load it locally for testing: |
| 156 | + |
| 157 | +```sh |
| 158 | +docker buildx build --platform linux/amd64 -t ontologies:amd64 --load . |
| 159 | +``` |
| 160 | + |
| 161 | +### Run The Published Image |
| 162 | + |
| 163 | +To deploy the published container on a server: |
| 164 | + |
| 165 | +```sh |
| 166 | +docker login -u <dockerhub-username> |
| 167 | +docker pull <dockerhub-repository>:latest |
| 168 | +docker run -d --name ontologies --restart unless-stopped -p 80:80 <dockerhub-repository>:latest |
| 169 | +``` |
| 170 | + |
| 171 | +Replace `<dockerhub-username>` and `<dockerhub-repository>` with your Docker Hub account and repository values. |
0 commit comments