From efb89c368d3c423ed90e3535e6992493bbf134eb Mon Sep 17 00:00:00 2001 From: "ugo.bechameil" Date: Fri, 7 Aug 2026 19:03:38 +0200 Subject: [PATCH 1/5] docs(hck-cli): lead with pre-built image and bump examples to 8.12.7 Update compose, k8s manifests, and guides from 8.9.2 to the current Hackolade Studio release. Reword the root README to surface hackolade/hck-cli as the primary getting-started path. Co-authored-by: Cursor --- README.md | 20 +++++++++-- Studio/compose.hardened.yml | 2 +- Studio/compose.yml | 2 +- Studio/doc/custom-certificates.md | 6 ++-- Studio/doc/getting-started-hck-cli.md | 50 +++++++++++++-------------- Studio/doc/getting-started.md | 2 +- Studio/k8s/hck-cli-gendoc-job.yaml | 2 +- Studio/k8s/hck-cli-job-openshift.yaml | 2 +- Studio/k8s/hck-cli-job.yaml | 2 +- 9 files changed, 51 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index b2818a9..fda5141 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,19 @@ -# Running Hackolade Studio Command Line Interface in Docker containers +# Running Hackolade CLI in Docker -This repository contains instructions and files for running Hackolade Studio CLI using our official Docker image which can be found on [Docker Hub](https://hub.docker.com/r/hackolade/studio/tags). This image doesn't contain Hackolade Studio but provides a preconfigured runtime for running it inside Docker containers. +This repository provides **ready-to-use examples** for the pre-built [`hackolade/hck-cli`](https://hub.docker.com/r/hackolade/hck-cli/tags) image: Hackolade Studio CLI, all target plugins, and a hardened runtime layout (`/data` + `/tmp`) — no build step required. -Check [How to run Hackolade Studio with Docker](./Studio/README.md) in [./Studio subfolder](./Studio) for details. +![Docker Image Version (latest by date)](https://img.shields.io/docker/v/hackolade/hck-cli) + +**Start here:** [Getting started with hackolade/hck-cli](./Studio/doc/getting-started-hck-cli.md) + +The [`Studio/`](./Studio) folder includes: + +- [`compose.yml`](./Studio/compose.yml) — simple local Compose example +- [`compose.hardened.yml`](./Studio/compose.hardened.yml) — read-only rootfs, dropped capabilities (Kubernetes Restricted parity) +- [`k8s/`](./Studio/k8s/) — Job manifests with PVC at `/data` and memory `emptyDir` at `/tmp` + +## Custom-built images (advanced) + +If you need a custom plugin set or a bespoke image, you can still build on the [`hackolade/studio`](https://hub.docker.com/r/hackolade/studio/tags) runtime base image. That path requires a build step and uses the legacy `/home/hackolade/Documents/*` layout. + +See [Building your own image](./Studio/doc/getting-started.md) and [build.md](./Studio/doc/build.md). diff --git a/Studio/compose.hardened.yml b/Studio/compose.hardened.yml index 63f395d..2fa617f 100644 --- a/Studio/compose.hardened.yml +++ b/Studio/compose.hardened.yml @@ -29,7 +29,7 @@ services: hck-cli: &hck-cli init: true - image: hackolade/hck-cli:8.9.2 + image: hackolade/hck-cli:8.12.7 command: ["version"] restart: 'no' read_only: true diff --git a/Studio/compose.yml b/Studio/compose.yml index 076a730..9c3728a 100644 --- a/Studio/compose.yml +++ b/Studio/compose.yml @@ -28,7 +28,7 @@ services: # --model '/data/models/MongoDB/Yelp Challenge dataset.hck.json' \ # --doc /data/output/doc-test --jsonSchema hck-cli: &hck-cli - image: hackolade/hck-cli:8.9.2 + image: hackolade/hck-cli:8.12.7 command: ["version"] restart: 'no' # network_mode: 'none' diff --git a/Studio/doc/custom-certificates.md b/Studio/doc/custom-certificates.md index d8529a3..e9c3daa 100644 --- a/Studio/doc/custom-certificates.md +++ b/Studio/doc/custom-certificates.md @@ -32,7 +32,7 @@ Use PEM format — the file starts with `-----BEGIN CERTIFICATE-----`. A single ```yaml services: hck-cli: - image: hackolade/hck-cli:8.9.2 + image: hackolade/hck-cli:8.12.7 command: ["version"] read_only: true user: "1000:1001" @@ -60,7 +60,7 @@ Reverse-engineering connectors and Git integration that use OpenSSL rather than ```bash mkdir -p certificates -docker run --rm --entrypoint cat hackolade/hck-cli:8.9.2 \ +docker run --rm --entrypoint cat hackolade/hck-cli:8.12.7 \ /etc/ssl/certs/ca-certificates.crt > certificates/ca-bundle.crt cat certificates/internal-ca.crt >> certificates/ca-bundle.crt ``` @@ -85,7 +85,7 @@ Mount the CA from a `ConfigMap` or `Secret` and set the variable. No init contai spec: containers: - name: hck-cli - image: hackolade/hck-cli:8.9.2 + image: hackolade/hck-cli:8.12.7 env: - name: NODE_EXTRA_CA_CERTS value: /certs/internal-ca.crt diff --git a/Studio/doc/getting-started-hck-cli.md b/Studio/doc/getting-started-hck-cli.md index b6de9c7..108f6b1 100644 --- a/Studio/doc/getting-started-hck-cli.md +++ b/Studio/doc/getting-started-hck-cli.md @@ -8,11 +8,11 @@ Before you begin, please note these critical requirements: - **Floating licenses only**: for Docker, you must have a Hackolade Studio **floating** license type (a.k.a. concurrent license key), as dedicated licenses won't work with Docker - **License is tied to the Docker image**: Each image version has a unique UUID, so you must validate the license for each version you use. If you change image versions, you'll need to validate the license again for the new image. -- **Always specify version tags**: the `latest` tag is not published. Use `hackolade/hck-cli:8.9.2` or intermediate tags like `8.9.2-YYYY-MM-DD` for plugin updates +- **Always specify version tags**: the `latest` tag is not published. Use `hackolade/hck-cli:8.12.7` or intermediate tags like `8.12.7-YYYY-MM-DD` for plugin updates - **Use Docker secrets** for license keys in production environments - **Data paths are simplified**: use `/data/*` instead of `/home/hackolade/Documents/*` -> **🚨 CRITICAL - Plugin Updates Policy:** Plugin updates between releases are **ONLY** available via intermediate tags from the **latest release** (e.g., `hackolade/hck-cli:8.9.2-YYYY-MM-DD`). **Plugin updates will NOT be backported to previous released images.** To get the latest plugin updates, you must use intermediate tags from the most recent release or wait for the next full release. +> **🚨 CRITICAL - Plugin Updates Policy:** Plugin updates between releases are **ONLY** available via intermediate tags from the **latest release** (e.g., `hackolade/hck-cli:8.12.7-YYYY-MM-DD`). **Plugin updates will NOT be backported to previous released images.** To get the latest plugin updates, you must use intermediate tags from the most recent release or wait for the next full release. ## What is this image? @@ -24,7 +24,7 @@ The `hackolade/hck-cli` Docker image is a pre-built, production-ready image that **Key advantages:** - No need to build your own image -- Versioned releases starting from 8.9.2 with optional intermediate tags for plugin updates +- Versioned releases aligned with Hackolade Studio, with optional intermediate tags for plugin updates - Simplified data paths (`/data` instead of `/home/hackolade/Documents/...`) - Secure secret management using Docker secrets - Backward compatible with existing scripts @@ -63,12 +63,12 @@ The image is published on Docker Hub under the `hackolade/hck-cli` repository an **Image naming convention:** -- `hackolade/hck-cli:8.9.2` : Initial release version (starting from 8.9.2) -- `hackolade/hck-cli:8.9.2-YYYY-MM-DD` -:Intermediate tags for plugin updates during the week (e.g., `8.9.2-2025-01-10`) +- `hackolade/hck-cli:8.12.7` : Current Hackolade Studio release +- `hackolade/hck-cli:8.12.7-YYYY-MM-DD` : Intermediate tags for plugin updates during the week (e.g., `8.12.7-2026-08-07`) **Note:** The `latest` tag is not currently published. Always specify a version tag when pulling or referencing the image. If plugins are updated during the week, intermediate tags with the format `X.Y.Z-` may be published to provide access to updated plugins before the next full release. -> **🚨 Plugin Updates Policy:** Plugin updates between releases are **ONLY** available via intermediate tags from the **latest release** (e.g., `hackolade/hck-cli:8.9.2-YYYY-MM-DD`). **Plugin updates will NOT be backported to previous released images.** To get the latest plugin updates, you must use intermediate tags from the most recent release or wait for the next full release. +> **🚨 Plugin Updates Policy:** Plugin updates between releases are **ONLY** available via intermediate tags from the **latest release** (e.g., `hackolade/hck-cli:8.12.7-YYYY-MM-DD`). **Plugin updates will NOT be backported to previous released images.** To get the latest plugin updates, you must use intermediate tags from the most recent release or wait for the next full release. **Platform support:** - **AMD64/x86_64** : Linux and Windows (Intel/AMD processors) @@ -180,7 +180,7 @@ Pull the image from Docker Hub using Docker Compose. Always specify a version ta docker compose pull ``` -This will pull the image version specified in your `compose.yml` file (`hackolade/hck-cli:8.9.2`). For intermediate releases with plugin updates, update the image tag in your `compose.yml` to the date-based tag (e.g., `hackolade/hck-cli:8.9.2-2025-01-10`) and run `docker compose pull` again. +This will pull the image version specified in your `compose.yml` file (`hackolade/hck-cli:8.12.7`). For intermediate releases with plugin updates, update the image tag in your `compose.yml` to the date-based tag (e.g., `hackolade/hck-cli:8.12.7-2026-08-07`) and run `docker compose pull` again. ### Step 4: Validate Your License @@ -341,7 +341,7 @@ docker run --rm --read-only \ -v hackolade-studio-data:/data \ -v ${PWD}/models:/data/models \ --tmpfs /tmp:rw,size=1g,mode=1777 \ - hackolade/hck-cli:8.9.2 COMMAND [OPTIONS] + hackolade/hck-cli:8.12.7 COMMAND [OPTIONS] ``` ### Create Required Volumes @@ -362,7 +362,7 @@ docker run --rm --read-only \ --user 1000:1001 \ -v hackolade-studio-data:/data \ --tmpfs /tmp:rw,size=1g,mode=1777 \ - hackolade/hck-cli:8.9.2 version + hackolade/hck-cli:8.12.7 version ``` **Get computer ID:** @@ -371,7 +371,7 @@ docker run --rm --read-only \ --user 1000:1001 \ -v hackolade-studio-data:/data \ --tmpfs /tmp:rw,size=1g,mode=1777 \ - hackolade/hck-cli:8.9.2 getComputerId + hackolade/hck-cli:8.12.7 getComputerId ``` **Generate documentation:** @@ -381,7 +381,7 @@ docker run --rm --read-only \ -v hackolade-studio-data:/data \ -v ${PWD}/models:/data/models \ --tmpfs /tmp:rw,size=1g,mode=1777 \ - hackolade/hck-cli:8.9.2 genDoc \ + hackolade/hck-cli:8.12.7 genDoc \ --format=HTML \ --model /data/models/model.json \ --doc /data/output/doc.html @@ -394,7 +394,7 @@ docker run --rm --read-only \ -v ${PWD}/models:/data/models \ -v ${PWD}/LicenseFile.xml:/data/LicenseFile.xml:ro \ --tmpfs /tmp:rw,size=1g,mode=1777 \ - hackolade/hck-cli:8.9.2 genDoc \ + hackolade/hck-cli:8.12.7 genDoc \ --format=HTML \ --model /data/models/model.json \ --doc /data/output/doc.html @@ -454,7 +454,7 @@ While you can pass license keys via environment variables, this is **not recomme # NOT RECOMMENDED for production docker run --rm \ -e LICENSE_KEY="your-key-here" \ - hackolade/hck-cli:8.9.2 validateKey --key ${LICENSE_KEY} + hackolade/hck-cli:8.12.7 validateKey --key ${LICENSE_KEY} ``` **Why secrets are better:** @@ -531,7 +531,7 @@ docker run --rm --init \ -v hackolade-studio-output:/output \ -v ${PWD}/output:/output-on-host \ --entrypoint cp \ - hackolade/hck-cli:8.9.2 -r /output /output-on-host/. + hackolade/hck-cli:8.12.7 -r /output /output-on-host/. ``` **Retrieve log files:** @@ -542,7 +542,7 @@ docker run --rm --init \ -v hackolade-studio-logs:/logs \ -v ${PWD}/logs:/logs-on-host \ --entrypoint cp \ - hackolade/hck-cli:8.9.2 -r /logs /logs-on-host/. + hackolade/hck-cli:8.12.7 -r /logs /logs-on-host/. ``` **Log organization:** Logs in `/data/logs` are automatically organized in folders using the format `-command` (e.g., `2024-01-15-genDoc`, `2024-01-15-forweng`). This structure makes it easy to isolate and analyze logs for specific operations by date and command type. When troubleshooting issues, you can focus on logs from the specific command and date that encountered a problem. @@ -630,7 +630,7 @@ If you get "image not found" errors: 2. **If using Docker CLI directly**, pull the image explicitly with a version tag (the `latest` tag is not available): ```bash - docker pull hackolade/hck-cli:8.9.2 + docker pull hackolade/hck-cli:8.12.7 ``` 3. Check available tags on [Docker Hub](https://hub.docker.com/r/hackolade/hck-cli/tags) @@ -639,7 +639,7 @@ If you get "image not found" errors: 5. If you need an intermediate release with plugin updates, update the image tag in your `compose.yml` (or use `docker pull` with the date-based tag): ```bash - docker pull hackolade/hck-cli:8.9.2-2025-01-10 + docker pull hackolade/hck-cli:8.12.7-2026-08-07 ``` ### Platform/Architecture Verification @@ -658,19 +658,19 @@ uname -m **Verify the pulled image architecture:** ```bash -docker image inspect hackolade/hck-cli:8.9.2 | grep Architecture +docker image inspect hackolade/hck-cli:8.12.7 | grep Architecture ``` **macOS Silicon users:** If you see `amd64` instead of `arm64`, Docker may be using emulation. To force ARM64 architecture: ```bash -docker pull --platform linux/arm64 hackolade/hck-cli:8.9.2 +docker pull --platform linux/arm64 hackolade/hck-cli:8.12.7 ``` Or in your `compose.yml`, specify the platform: ```yaml services: hck-cli: - image: hackolade/hck-cli:8.9.2 + image: hackolade/hck-cli:8.12.7 platform: linux/arm64 # For Apple Silicon # platform: linux/amd64 # For Intel/AMD ``` @@ -716,7 +716,7 @@ docker compose run --rm hck-cli COMMAND [OPTIONS] ```bash # Pull the image (always specify a version tag) -docker pull hackolade/hck-cli:8.9.2 +docker pull hackolade/hck-cli:8.12.7 # Create volumes docker volume create hackolade-studio-data @@ -727,7 +727,7 @@ docker run --rm --read-only \ -v hackolade-studio-data:/data \ -v ${PWD}/models:/data/models \ --tmpfs /tmp:rw,size=1g,mode=1777 \ - hackolade/hck-cli:8.9.2 COMMAND + hackolade/hck-cli:8.12.7 COMMAND ``` ## Kubernetes (restricted / read-only rootfs) @@ -781,7 +781,7 @@ spec: sizeLimit: 1Gi containers: - name: hck-cli - image: hackolade/hck-cli:8.9.2 + image: hackolade/hck-cli:8.12.7 args: ["version"] securityContext: allowPrivilegeEscalation: false @@ -805,10 +805,10 @@ You can override the entrypoint to use these scripts if needed: ```bash # Use show-computer-id.sh script (alternative to getComputerId command) -docker run --rm --entrypoint show-computer-id.sh hackolade/hck-cli:8.9.2 +docker run --rm --entrypoint show-computer-id.sh hackolade/hck-cli:8.12.7 # Use startup.sh script (alternative to direct hck-cli entrypoint) -docker run --rm --entrypoint startup.sh hackolade/hck-cli:8.9.2 COMMAND [OPTIONS] +docker run --rm --entrypoint startup.sh hackolade/hck-cli:8.12.7 COMMAND [OPTIONS] ``` **Note:** While these scripts are available for compatibility, the recommended approach is to use the `hck-cli` binary directly as the entrypoint, which provides better performance and simpler usage. diff --git a/Studio/doc/getting-started.md b/Studio/doc/getting-started.md index 812b7dc..45f6c67 100644 --- a/Studio/doc/getting-started.md +++ b/Studio/doc/getting-started.md @@ -74,7 +74,7 @@ If you are currently using a custom-built image based on `hackolade/studio` and **Key differences you need to update:** -1. **Image reference**: Change from your custom image tag to `hackolade/hck-cli:8.9.2` (or appropriate version) +1. **Image reference**: Change from your custom image tag to `hackolade/hck-cli:8.12.7` (or appropriate version) 2. **Data paths**: Update volume mounts from `/home/hackolade/Documents/*` to `/data/*` - `/home/hackolade/Documents/models` → `/data/models` - `/home/hackolade/Documents/output` → `/data/output` diff --git a/Studio/k8s/hck-cli-gendoc-job.yaml b/Studio/k8s/hck-cli-gendoc-job.yaml index 2c9430b..4c6b504 100644 --- a/Studio/k8s/hck-cli-gendoc-job.yaml +++ b/Studio/k8s/hck-cli-gendoc-job.yaml @@ -41,7 +41,7 @@ spec: sizeLimit: 1Gi containers: - name: hck-cli - image: hackolade/hck-cli:8.9.2 + image: hackolade/hck-cli:8.12.7 args: - genDoc - --model=/data/models/smoke.hck.json diff --git a/Studio/k8s/hck-cli-job-openshift.yaml b/Studio/k8s/hck-cli-job-openshift.yaml index a78a5dd..84a6494 100644 --- a/Studio/k8s/hck-cli-job-openshift.yaml +++ b/Studio/k8s/hck-cli-job-openshift.yaml @@ -59,7 +59,7 @@ spec: sizeLimit: 1Gi containers: - name: hck-cli - image: hackolade/hck-cli:8.9.2 + image: hackolade/hck-cli:8.12.7 args: ["version"] securityContext: allowPrivilegeEscalation: false diff --git a/Studio/k8s/hck-cli-job.yaml b/Studio/k8s/hck-cli-job.yaml index b002b69..356526c 100644 --- a/Studio/k8s/hck-cli-job.yaml +++ b/Studio/k8s/hck-cli-job.yaml @@ -55,7 +55,7 @@ spec: sizeLimit: 1Gi containers: - name: hck-cli - image: hackolade/hck-cli:8.9.2 + image: hackolade/hck-cli:8.12.7 args: ["version"] securityContext: allowPrivilegeEscalation: false From 27e487835a74cdf50d3a58b187d2e365956ffd97 Mon Sep 17 00:00:00 2001 From: Ugo Bechameil <12494392+bigorn0@users.noreply.github.com> Date: Fri, 7 Aug 2026 19:12:36 +0200 Subject: [PATCH 2/5] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fda5141..5559c04 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ The [`Studio/`](./Studio) folder includes: - [`compose.hardened.yml`](./Studio/compose.hardened.yml) — read-only rootfs, dropped capabilities (Kubernetes Restricted parity) - [`k8s/`](./Studio/k8s/) — Job manifests with PVC at `/data` and memory `emptyDir` at `/tmp` -## Custom-built images (advanced) +## Custom-built images (legacy. runtime) If you need a custom plugin set or a bespoke image, you can still build on the [`hackolade/studio`](https://hub.docker.com/r/hackolade/studio/tags) runtime base image. That path requires a build step and uses the legacy `/home/hackolade/Documents/*` layout. From 6be5b429b6fb00dfa0e69cbb6f765cf64ab73107 Mon Sep 17 00:00:00 2001 From: Ugo Bechameil <12494392+bigorn0@users.noreply.github.com> Date: Fri, 7 Aug 2026 19:12:47 +0200 Subject: [PATCH 3/5] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5559c04..b530c79 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ The [`Studio/`](./Studio) folder includes: - [`compose.hardened.yml`](./Studio/compose.hardened.yml) — read-only rootfs, dropped capabilities (Kubernetes Restricted parity) - [`k8s/`](./Studio/k8s/) — Job manifests with PVC at `/data` and memory `emptyDir` at `/tmp` -## Custom-built images (legacy. runtime) +## Custom-built images (legacy runtime) If you need a custom plugin set or a bespoke image, you can still build on the [`hackolade/studio`](https://hub.docker.com/r/hackolade/studio/tags) runtime base image. That path requires a build step and uses the legacy `/home/hackolade/Documents/*` layout. From d4cb94c15a95d3d8db43622d63036666e0c8c462 Mon Sep 17 00:00:00 2001 From: "ugo.bechameil" Date: Fri, 7 Aug 2026 19:58:03 +0200 Subject: [PATCH 4/5] docs(hck-cli): simplify getting started and fix k8s README Rewrite k8s/README.md as normal Markdown (was YAML-style comments that rendered poorly on GitHub). Cut getting-started-hck-cli.md to a focused quick-start and link out to license, certs, hardened compose, and k8s docs. Reorder Studio/README to lead with hackolade/hck-cli. Co-authored-by: Cursor --- Studio/README.md | 49 +- Studio/doc/getting-started-hck-cli.md | 817 ++------------------------ Studio/k8s/README.md | 60 +- 3 files changed, 118 insertions(+), 808 deletions(-) diff --git a/Studio/README.md b/Studio/README.md index 34cc054..b015baf 100644 --- a/Studio/README.md +++ b/Studio/README.md @@ -1,48 +1,37 @@ # Running Hackolade Studio CLI in Docker -![Docker Image Version (latest by date)](https://img.shields.io/docker/v/hackolade/studio) +![Docker Image Version (latest by date)](https://img.shields.io/docker/v/hackolade/hck-cli) -The instructions below assume that you have Docker [installed](https://www.docker.com/get-started) and running. +The purpose of running Hackolade in a Docker container is to operate the **Command-Line Interface (CLI)**, typically in CI/CD pipelines. -The purpose of running Hackolade Studio in a Docker container is to operate the Command-Line Interface ("CLI"), typically in a the context of integration with CI/CD pipelines. +⚠ The purpose is **not** to run the application GUI in Docker — this is **not** supported. -⚠ The purpose is **not** to run the application GUI in Docker -- this is **not** supported. +The instructions below assume Docker is [installed](https://www.docker.com/get-started) and running. -## 🚀 Getting Started +## 🚀 Getting started (recommended) -**New to Docker or need step-by-step instructions?** Start with our comprehensive [Getting Started Guide](./doc/getting-started.md) which includes: -- Docker basics explained in simple terms -- Instructions using **Docker CLI directly** (for beginners and those who want explicit control) -- Instructions using **Docker Compose** (for simpler, shorter commands) -- Complete examples for common scenarios -- Troubleshooting tips +Use the pre-built [`hackolade/hck-cli`](https://hub.docker.com/r/hackolade/hck-cli/tags) image — Hackolade Studio CLI with all plugins, no build step: -The guide is designed to be understandable even if you've never used Docker before. +**[Getting started with hackolade/hck-cli](./doc/getting-started-hck-cli.md)** -## 🎯 Using the Pre-built CLI Image (Recommended) +Includes [`compose.yml`](./compose.yml), [`compose.hardened.yml`](./compose.hardened.yml) (read-only rootfs), and [`k8s/`](./k8s/) Job examples. -**Want to skip the build step?** We now provide a ready-to-use Docker image (`hackolade/hck-cli`) that includes Hackolade Studio and all plugins pre-installed. This is the fastest way to get started! +## Build your own image (advanced) -**Benefits:** -- ✅ No build step required - just pull and use -- ✅ Simplified data paths (`/data` instead of `/home/hackolade/Documents/...`) -- ✅ Secure secret management for license keys -- ✅ Always up-to-date with latest releases +Need a custom plugin set or Dockerfile based on [`hackolade/studio`](https://hub.docker.com/r/hackolade/studio/tags)? See [getting-started.md](./doc/getting-started.md) and [build.md](./doc/build.md). -**Get started:** See our [Getting Started Guide for the Pre-built CLI Image](./doc/getting-started-hck-cli.md) for complete instructions. +## Repository structure -**When to use the pre-built image vs. building your own:** -- **Use pre-built image** (`hackolade/hck-cli`) if you want simplicity and all plugins included -- **Build your own** (instructions below) if you need specific plugin versions or customizations +Primary examples use the pre-built **`hackolade/hck-cli`** image: -## Repository structure -This repository contains files and instructions for running the [Hackolade Studio](https://hackolade.com) data modeling application, using the base image published on [Docker Hub](https://hub.docker.com/r/hackolade/studio): +- [compose.yml](compose.yml): simple local Compose example +- [compose.hardened.yml](compose.hardened.yml): read-only rootfs, `/data` + `/tmp` tmpfs +- [k8s/](k8s/): Kubernetes Job manifests (PVC + memory emptyDir) + +Custom-build path (legacy layout on `hackolade/studio`): -- [Dockerfile](Dockerfile): ready-to-use example of a full installation of Hackolade Studio, including the possibility to install selected target plugins -- [docker-compose.yml](docker-compose.yml): example for **custom-built** `hackolade/studio` images (traditional paths) -- [compose.yml](compose.yml): simple example for the pre-built **`hackolade/hck-cli`** image -- [compose.hardened.yml](compose.hardened.yml): hardened `hck-cli` example (read-only rootfs, `/data` + `/tmp` tmpfs) -- [k8s/](k8s/): Kubernetes Job examples with PVC at `/data` and memory emptyDir at `/tmp` +- [Dockerfile](Dockerfile): example full installation with selected plugins +- [docker-compose.yml](docker-compose.yml): Compose for custom-built images - [securityPolicies.json](securityPolicies.json) - [optional] the list of required system call operations to be able to run Hackolade with Chrome sandboxing (disabled by default) inside a container ([more details](https://docs.docker.com/engine/security/seccomp/)) - batch files examples when running on Windows: - [docker-help.bat](docker-help.bat): verify the proper running of the CLI by displaying the CLI help in a container. Will work without a validated license key. diff --git a/Studio/doc/getting-started-hck-cli.md b/Studio/doc/getting-started-hck-cli.md index 108f6b1..6267d74 100644 --- a/Studio/doc/getting-started-hck-cli.md +++ b/Studio/doc/getting-started-hck-cli.md @@ -1,814 +1,115 @@ -This guide will help you get started with the **ready-to-use** Hackolade CLI Docker image (`hackolade/hck-cli`). This image contains Hackolade Studio and all plugins pre-installed, so you can use it directly without building your own image. +# Getting started with `hackolade/hck-cli` -![Docker Image Version (latest by date)](https://img.shields.io/docker/v/hackolade/hck-cli) - -## ⚠️ Important notes - -Before you begin, please note these critical requirements: - -- **Floating licenses only**: for Docker, you must have a Hackolade Studio **floating** license type (a.k.a. concurrent license key), as dedicated licenses won't work with Docker -- **License is tied to the Docker image**: Each image version has a unique UUID, so you must validate the license for each version you use. If you change image versions, you'll need to validate the license again for the new image. -- **Always specify version tags**: the `latest` tag is not published. Use `hackolade/hck-cli:8.12.7` or intermediate tags like `8.12.7-YYYY-MM-DD` for plugin updates -- **Use Docker secrets** for license keys in production environments -- **Data paths are simplified**: use `/data/*` instead of `/home/hackolade/Documents/*` - -> **🚨 CRITICAL - Plugin Updates Policy:** Plugin updates between releases are **ONLY** available via intermediate tags from the **latest release** (e.g., `hackolade/hck-cli:8.12.7-YYYY-MM-DD`). **Plugin updates will NOT be backported to previous released images.** To get the latest plugin updates, you must use intermediate tags from the most recent release or wait for the next full release. - -## What is this image? - -The `hackolade/hck-cli` Docker image is a pre-built, production-ready image that includes: -- Hackolade Studio CLI binary (`hck-cli`) -- note that hck-cli in this Docker image replaces the "hackolade" invocation found in the CLI documentation page -- All target plugins pre-installed -- Optimized data volume structure at `/data` (reducing path length and complexity) -- Ready to use immediately - no build step required - -**Key advantages:** -- No need to build your own image -- Versioned releases aligned with Hackolade Studio, with optional intermediate tags for plugin updates -- Simplified data paths (`/data` instead of `/home/hackolade/Documents/...`) -- Secure secret management using Docker secrets -- Backward compatible with existing scripts -- Multi-architecture support (AMD64/x86_64 and ARM64) - runs efficiently on macOS Silicon (Apple MX chips) without emulation overhead -- Automatic volume validation - CLI warns if required volumes are not mounted -- Per-command log isolation in `/data/logs` organized as `-command` folders for easier troubleshooting and log analysis - -## Differences from building your own image - -| Feature | Pre-built Image (`hackolade/hck-cli`) | Building Your Own (hackolade/studio) | -|---------|--------------------------------------|-------------------| -| Setup time | Instant (just pull) | Requires build step | -| Data paths | `/data/*` (simplified) | `/home/hackolade/Documents/*` | -| Entrypoint | `hck-cli` binary | `startup.sh` script | -| Updates | Pull new version | Rebuild image | -| Plugins | All included | Select during build | -| Architecture support | Multi-arch (AMD64 + ARM64) | AMD64/x86_64 only (Intel-based chips) | -| Customization | Limited | Full control | - -**When to use the pre-built image:** -- You want to get started quickly -- You need all plugins -- You prefer simplicity over customization -- You're running in CI/CD pipelines -- You're using macOS Silicon (Apple MX) and want efficient ARM64 performance without emulation - -**When to build your own:** -- You need specific plugin versions -- You want to customize the image -- You have specific security requirements -- See [build.md](./build.md) for instructions - -## Image availability - -The image is published on Docker Hub under the `hackolade/hck-cli` repository and will be available for each release of Hackolade Studio alongside the existing `hackolade/studio` image. - - -**Image naming convention:** -- `hackolade/hck-cli:8.12.7` : Current Hackolade Studio release -- `hackolade/hck-cli:8.12.7-YYYY-MM-DD` : Intermediate tags for plugin updates during the week (e.g., `8.12.7-2026-08-07`) - -**Note:** The `latest` tag is not currently published. Always specify a version tag when pulling or referencing the image. If plugins are updated during the week, intermediate tags with the format `X.Y.Z-` may be published to provide access to updated plugins before the next full release. - -> **🚨 Plugin Updates Policy:** Plugin updates between releases are **ONLY** available via intermediate tags from the **latest release** (e.g., `hackolade/hck-cli:8.12.7-YYYY-MM-DD`). **Plugin updates will NOT be backported to previous released images.** To get the latest plugin updates, you must use intermediate tags from the most recent release or wait for the next full release. - -**Platform support:** -- **AMD64/x86_64** : Linux and Windows (Intel/AMD processors) -- **ARM64** : Linux ARM64 and **macOS Silicon** (Apple MX chips) - -Docker automatically pulls the correct architecture image for your platform. If you're running on macOS Silicon (Apple Silicon), Docker Desktop will automatically use the ARM64 image, providing efficient performance without emulation overhead. - -## Prerequisites - -Before you begin, make sure you have: -1. **Docker installed** on your system ([Install Docker](https://www.docker.com/get-started)) - - **macOS Silicon users:** Docker Desktop for Mac includes ARM64 support -2. **Docker Compose** installed (v2.0+ recommended) -3. **Docker is running** (check by running `docker --version` in your terminal) -4. A **floating Hackolade license key** (required for Docker CLI usage) - -**Note for macOS Silicon users:** The image includes ARM64 support, so it runs efficiently on Apple Silicon Macs (MX) without emulation overhead. Docker Desktop automatically selects the correct architecture. - -## Understanding the image structure - -### Entrypoint - -The image uses `hck-cli` as its default entrypoint - a simple binary that executes Hackolade CLI commands directly. This provides the most straightforward and efficient way to run commands. - -### Data Volume Structure - -The image is designed for a **read-only root filesystem**. Runtime writes go to exactly two places: - -| Mount | Purpose | -| --- | --- | -| `/data` | Persistent volume: license/userData (`/data/app`), logs, models, output, settings, options | -| `/tmp` | tmpfs: sockets, caches, and scratch files (discarded when the container exits) | - -Layout under `/data`: - -- `/data/app` - Application data (license state, Electron userData). Lives on the `/data` volume via `XDG_CONFIG_HOME`. -- `/data/models` - Your input model files -- `/data/output` - Generated artifacts (documentation, schemas, etc.) -- `/data/logs` - Application logs organized in `-command` folders (e.g., `2024-01-15-genDoc`) for per-command isolation and troubleshooting -- `/data/options` - (Optional) User-defined configurations -- `/data/settings` - Optional settings - -**⚠️ MANDATORY:** Mount a volume at `/data` **and** a writable `/tmp` (tmpfs recommended). Without `/data`, licensing and configuration will not persist. Without `/tmp`, Electron and scratch I/O will fail under `read_only: true`. - -**Breaking change:** Earlier releases required a separate volume at `/home/hackolade/.config`. That path is no longer written; migrate the named volume to `/data` (license state is under `/data/app`). +Ready-to-use Docker image: Hackolade Studio CLI, all target plugins, no build step. -**Volume validation:** The CLI automatically validates that required mounts are writable. If a required mount is missing, the CLI will display a warning (or fail in the official image) before command execution. - -**Log isolation:** Logs are automatically organized per command in `/data/logs` using folders named `-command` (e.g., `2024-01-15-genDoc`, `2024-01-15-forweng`). This folder structure provides proper command isolation, making it easier to analyze logs for specific commands when troubleshooting issues. - -## Quick start with Docker Compose - -The easiest way to use this image is with Docker Compose. We provide two example files: - -| File | Use when | -| --- | --- | -| [`compose.yml`](../compose.yml) | Getting started locally — minimal configuration, single `/data` volume | -| [`compose.hardened.yml`](../compose.hardened.yml) | Production or CI — read-only root filesystem, dropped capabilities, `/data` + `/tmp` tmpfs (matches Kubernetes Restricted) | - -**Important:** Both files are designed for the **pre-built `hackolade/hck-cli` image**. They use `/data/*` paths and the `hck-cli` binary entrypoint, which differ from compose files used with custom-built images. - -### Step 1: Set Up Your Compose File - -**Option A: Copy the provided compose file** (recommended for first use) - -Copy [`compose.yml`](../compose.yml) to your working directory: - -```bash -cp compose.yml /path/to/your/working/directory/ -``` - -**Option B: Use the hardened compose file** (recommended for production / Kubernetes parity) - -Copy [`compose.hardened.yml`](../compose.hardened.yml) instead, or alongside `compose.yml`: - -```bash -cp compose.hardened.yml /path/to/your/working/directory/ -docker compose -f compose.hardened.yml run --rm hck-cli version -``` +![Docker Image Version (latest by date)](https://img.shields.io/docker/v/hackolade/hck-cli) -**Option C: Create your own compose file** +## Before you start -See [`compose.yml`](../compose.yml) for a simple example and [`compose.hardened.yml`](../compose.hardened.yml) for the restricted profile. +- **Floating license only** — workstation licenses do not work in Docker. +- **Pin a version tag** — `latest` is not published. Example: `hackolade/hck-cli:8.12.7`. Weekly plugin refreshes may appear as `8.12.7-YYYY-MM-DD` on the [current release only](https://hub.docker.com/r/hackolade/hck-cli/tags). +- **Re-validate when the image tag changes** — license state is tied to the image UUID. +- **Two writable mounts** — persistent `/data` plus writable `/tmp` (tmpfs in hardened setups). -The compose files include: -- `hck-cli` service — main service for running CLI commands -- `showComputerIdForOfflineValidation` — computer ID for offline license validation -- `validateKeyOnline` / `validateKeyOffline` — license validation via Docker secrets -- A single named volume at `/data` (license state, logs, models, output, settings) -- Secret definitions for license key and license file -- (`compose.hardened.yml` only) read-only root filesystem, `cap_drop: ALL`, and `/tmp` tmpfs +Need a custom plugin set or your own Dockerfile? See [getting-started.md](./getting-started.md) (build on `hackolade/studio`). -### Step 2: Create Your Models Directory +## Quick start (Docker Compose) -Create a directory for your model files: +1. Copy [`compose.yml`](../compose.yml) and create a models folder: ```bash +cp compose.yml . mkdir -p ./models -chown -R 1000:1001 ./models ``` -**Why `chown 1000:1001`?** The container runs as user `hackolade` with UID 1000 and GID 1001 (data-modelers group). This ensures the folder is writable by the container. - -### Step 3: Pull the Image - -Pull the image from Docker Hub using Docker Compose. Always specify a version tag (the `latest` tag is not available): +2. Pull and check the image: ```bash docker compose pull -``` - -This will pull the image version specified in your `compose.yml` file (`hackolade/hck-cli:8.12.7`). For intermediate releases with plugin updates, update the image tag in your `compose.yml` to the date-based tag (e.g., `hackolade/hck-cli:8.12.7-2026-08-07`) and run `docker compose pull` again. - -### Step 4: Validate Your License - -Before using the CLI, you must validate your license. This step must be performed for each new image, but only needs to be performed once. After validation has successfully completed, then all successions of commands can be orchestrated and invoked without having to validate the license key again. - -The compose file provides secure methods using Docker secrets. Choose the method that matches your environment: - -#### Online License Validation (Recommended) - -Use this method if your server has internet access. - -**Step 4a: Prepare your license key file** - -Create a file containing the floating license key you purchased for Docker. The path `${HOME}/Downloads/license-key.txt` is just an example. You can use any path you prefer, but make sure it matches the path in your `compose.yml` secrets section: - -```bash -# Example: Using ${HOME}/Downloads (adjust path as needed) -echo "YOUR-LICENSE-KEY" > ${HOME}/Downloads/license-key.txt -chmod 600 ${HOME}/Downloads/license-key.txt -``` - -**Step 4b: Validate the license** - -```bash -docker compose run --rm validateKeyOnline -``` - -The compose file automatically: -- Reads your license key from the secret file (path specified in `compose.yml` secrets section, e.g., `${HOME}/Downloads/license-key.txt`) -- Uses the correct network mode for online validation (`network_mode: host`) -- Stores the validated license in the persistent volume - -**Note:** For online validation, you don't need to get the computer ID separately. The validation process handles it automatically. - -#### Offline License Validation - -Use this method if your server has no internet access. - -**Step 4a: Get the computer ID** - -First, get the computer ID (UUID) that will be used to generate the offline license file: - -```bash -docker compose run --rm showComputerIdForOfflineValidation -``` - -Copy the UUID that's displayed (e.g., `420d1eaf-6e08-4e12-b4d1-103ab86565b4-0eec2df9-f40e-4623-9567-c2c287c95d0c-docker`). Note that Docker images will have the `-docker` suffix in the UUID. - -**Step 4b: Generate the license file** - -From a computer with internet access, open your browser and go to: -[https://quicklicensemanager.com/hackolade/QlmCustomerSite](https://quicklicensemanager.com/hackolade/QlmCustomerSite) - -Fill in the form: -- **Activation Key**: Enter your floating license key -- **Version**: Leave empty (or select the appropriate version if required) -- **Computer ID**: Enter the UUID from step 4a -- **Options**: Check both "Generate a license file" and "I consent to the Privacy Policy" -- Click the **Activate** button - -A file named **LicenseFile.xml** will be downloaded. **Do NOT edit or alter this file**. It contains integrity validation to prevent abuse. - -**Step 4c: Prepare the license file** - -Copy the **LicenseFile.xml** file to your server. The path `${HOME}/Downloads/LicenseFile.xml` is just an example. Use the path that matches your `compose.yml` secrets section: - -```bash -# Example: Using ${HOME}/Downloads (adjust path to match your compose.yml) -cp LicenseFile.xml ${HOME}/Downloads/LicenseFile.xml -chmod 600 ${HOME}/Downloads/LicenseFile.xml -``` - -**Step 4d: Validate the license** - -```bash -docker compose run --rm validateKeyOffline -``` - -The compose file automatically: -- Reads the license file from the secret (`${HOME}/Downloads/LicenseFile.xml`) -- Uses `network_mode: 'none'` to ensure no network access -- Stores the validated license in the persistent volume - -**Important:** The license is tied to the specific Docker image. You must use the **same Docker image** (same tag/version) for steps 4a and 4d, otherwise the UUIDs won't match and validation will fail. If you change the image version, you'll need to generate a new license file for that image. - -For more detailed offline validation instructions, see [license-validation.md](./license-validation.md). - -### Step 5: Run CLI Commands - -Now you're ready to run Hackolade CLI commands! - -**Basic command structure:** -```bash -docker compose run --rm hck-cli COMMAND [OPTIONS] -``` - -**Example: Check version** -```bash docker compose run --rm hck-cli version ``` -**Example: Show help** -```bash -docker compose run --rm hck-cli help -``` - -**Example: Generate documentation** -```bash -docker compose run --rm hck-cli genDoc \ - --format=HTML \ - --model '/data/models/MongoDB/Yelp Challenge dataset.hck.json' \ - --doc /data/output/doc-test \ - --jsonSchema -``` - -**Example: Forward engineering** -```bash -docker compose run --rm hck-cli forweng \ - --model /data/models/model.json \ - --jsonschemacompliance full \ - --skipUndefinedLevel \ - --structuredpath false \ - --path /data/output/ \ - --outputtype jsonschema -``` - -## Hardened Docker Compose (Kubernetes parity) - -For production clusters or CI pipelines that enforce the Kubernetes **Restricted** Pod Security Standard (or OpenShift **restricted-v2** SCC), use [`compose.hardened.yml`](../compose.hardened.yml). It adds: - -- `read_only: true` — read-only root filesystem -- `cap_drop: [ALL]` and `no-new-privileges` — no extra capabilities or privilege escalation -- `user: "1000:1001"` — non-root (OpenShift arbitrary UID variant included as `hck-cli-arbitrary-uid`) -- `/data` named volume — persistent state (same as `compose.yml`) -- `/tmp` tmpfs — scratch, sockets, and caches (discarded when the container exits) - -```bash -# Smoke test -docker compose -f compose.hardened.yml run --rm hck-cli version - -# OpenShift-style arbitrary UID -docker compose -f compose.hardened.yml run --rm hck-cli-arbitrary-uid version - -# Command that writes output (requires a model at ./models/smoke.hck.json) -docker compose -f compose.hardened.yml run --rm genDoc -``` - -## Using Docker CLI directly - -If you prefer using Docker CLI directly instead of Docker Compose, here's how: - -### Basic Command Structure - -```bash -docker run --rm --read-only \ - --cap-drop=ALL --security-opt=no-new-privileges \ - --user 1000:1001 \ - -v hackolade-studio-data:/data \ - -v ${PWD}/models:/data/models \ - --tmpfs /tmp:rw,size=1g,mode=1777 \ - hackolade/hck-cli:8.12.7 COMMAND [OPTIONS] -``` - -### Create Required Volumes - -First, create the named volume for persistent state: - -```bash -docker volume create hackolade-studio-data -``` - -`/tmp` should be a tmpfs (shown above), not a named volume. +3. Validate your license (online example — adjust secret paths in `compose.yml`): -### Example Commands - -**Check version:** -```bash -docker run --rm --read-only \ - --user 1000:1001 \ - -v hackolade-studio-data:/data \ - --tmpfs /tmp:rw,size=1g,mode=1777 \ - hackolade/hck-cli:8.12.7 version -``` - -**Get computer ID:** -```bash -docker run --rm --read-only \ - --user 1000:1001 \ - -v hackolade-studio-data:/data \ - --tmpfs /tmp:rw,size=1g,mode=1777 \ - hackolade/hck-cli:8.12.7 getComputerId -``` - -**Generate documentation:** -```bash -docker run --rm --read-only \ - --user 1000:1001 \ - -v hackolade-studio-data:/data \ - -v ${PWD}/models:/data/models \ - --tmpfs /tmp:rw,size=1g,mode=1777 \ - hackolade/hck-cli:8.12.7 genDoc \ - --format=HTML \ - --model /data/models/model.json \ - --doc /data/output/doc.html -``` -In case of offline validation: ```bash -docker run --rm --read-only \ - --user 1000:1001 \ - -v hackolade-studio-data:/data \ - -v ${PWD}/models:/data/models \ - -v ${PWD}/LicenseFile.xml:/data/LicenseFile.xml:ro \ - --tmpfs /tmp:rw,size=1g,mode=1777 \ - hackolade/hck-cli:8.12.7 genDoc \ - --format=HTML \ - --model /data/models/model.json \ - --doc /data/output/doc.html -``` - -## Security best practices - -### Using Docker Secrets for License Keys - -The compose file uses Docker secrets to securely manage license keys and files. This is the **recommended approach** for production environments. - -**Benefits:** -- Secrets are not exposed in command-line arguments -- Secrets are not visible in `docker ps` or container logs -- Secrets are managed by Docker and can be rotated easily -- Secrets are only available to services that explicitly request them - -**How it works:** - -1. **Define secrets in compose.yml:** - ```yaml - secrets: - license_key: # Don't change the name of the secret! - file: ${HOME}/Downloads/license-key.txt # Example path - use any path you prefer - license_file: # Don't change the name of the secret! - file: ${HOME}/Downloads/LicenseFile.xml # Example path - use any path you prefer - ``` - -2. **Reference secrets in services:** - ```yaml - validateKeyOnline: - secrets: - - license_key - ``` - -3. **The CLI automatically reads from standard secret paths:** - - License key: `/run/secrets/license_key` - - License file: `/run/secrets/license_file` - -**Securing your secret files:** - -```bash -# Set restrictive permissions on secret files (adjust paths to match your compose.yml) -chmod 600 ${HOME}/Downloads/license-key.txt -chmod 600 ${HOME}/Downloads/LicenseFile.xml - -# Consider using a more secure location (update compose.yml accordingly) -mkdir -p ~/.hackolade/secrets -chmod 700 ~/.hackolade/secrets -``` - -### Alternative: Environment Variables (Less Secure) - -While you can pass license keys via environment variables, this is **not recommended** for production: - -```bash -# NOT RECOMMENDED for production -docker run --rm \ - -e LICENSE_KEY="your-key-here" \ - hackolade/hck-cli:8.12.7 validateKey --key ${LICENSE_KEY} -``` - -**Why secrets are better:** -- Environment variables appear in process lists -- Environment variables can be logged -- Environment variables are harder to rotate - -### Network Security - -For maximum security, use `network_mode: 'none'` when validating licenses offline: - -```yaml -validateKeyOffline: - network_mode: 'none' - secrets: - - license_file +echo "YOUR-FLOATING-LICENSE-KEY" > ~/license-key.txt +chmod 600 ~/license-key.txt +docker compose run --rm validateKeyOnline ``` -This ensures the container has no network access during offline validation. - -## Common scenarios - -### Scenario 1: Generate Documentation +4. Run a command: ```bash docker compose run --rm hck-cli genDoc \ --format=HTML \ --model /data/models/my-model.hck.json \ - --doc /data/output/documentation \ - --jsonSchema -``` - -### Scenario 2: Forward Engineering - -```bash -docker compose run --rm hck-cli forweng \ - --model /data/models/my-model.hck.json \ - --jsonschemacompliance full \ - --skipUndefinedLevel \ - --structuredpath false \ - --path /data/output/schemas/ \ - --outputtype jsonschema -``` - -### Scenario 3: Reverse Engineering - -```bash -docker compose run --rm hck-cli revEng \ - --target=MONGODB \ - --connectFile=/data/models/connection.bin \ - --model=/data/output/reverse-engineered-model.json \ - --selectedObjects="database_name" \ - --inferRelationships=true -``` - -### Scenario 4: Compare Models - -```bash -docker compose run --rm hck-cli compMod \ - --model1=/data/models/model-v1.json \ - --model2=/data/models/model-v2.json \ - --deltamodel=/data/output/delta.json -``` - -## Retrieving generated files - -After running commands, retrieve files from Docker volumes (if you used named volumes): - -**Retrieve output files:** -```bash -docker run --rm --init \ - --name hackolade-data-extractor \ - -u root \ - -v hackolade-studio-output:/output \ - -v ${PWD}/output:/output-on-host \ - --entrypoint cp \ - hackolade/hck-cli:8.12.7 -r /output /output-on-host/. -``` - -**Retrieve log files:** -```bash -docker run --rm --init \ - --name hackolade-log-extractor \ - -u root \ - -v hackolade-studio-logs:/logs \ - -v ${PWD}/logs:/logs-on-host \ - --entrypoint cp \ - hackolade/hck-cli:8.12.7 -r /logs /logs-on-host/. -``` - -**Log organization:** Logs in `/data/logs` are automatically organized in folders using the format `-command` (e.g., `2024-01-15-genDoc`, `2024-01-15-forweng`). This structure makes it easy to isolate and analyze logs for specific operations by date and command type. When troubleshooting issues, you can focus on logs from the specific command and date that encountered a problem. - -## Troubleshooting - -### Permission Denied Errors - -If you get permission errors with bind-mounted folders (like `./models`), ensure correct permissions: - -```bash -chown -R 1000:1001 ./models -chown -R 1000:1001 ./output -``` - -**Note:** The container runs as numeric user `1000:1001` by default (compatible with Kubernetes `runAsNonRoot`). OpenShift-style arbitrary UIDs in group 0 are also supported when `/data` is group-writable. - -**Note:** Docker named volumes (like `hackolade-studio-data`) don't require permission changes on the host. Bind mounts for models should be owned by UID 1000 (or writable by group 0). - -### Volume Not Found - -If Docker says a volume doesn't exist, create it: - -```bash -docker volume create hackolade-studio-data + --doc /data/output/doc ``` -Or let Docker Compose create it automatically on first run. Ensure every run also mounts a writable `/tmp` (compose uses `tmpfs`). - -### Volume Validation Warnings - -The CLI automatically checks for required writable mounts and will warn you if they're not properly mounted. If you see warnings about missing mounts: - -1. **Check your compose.yml or docker run command** - Ensure: - - `hackolade-studio-data` → `/data` ⚠️ **MANDATORY** - license state, logs, output, settings - - tmpfs (or equivalent) → `/tmp` ⚠️ **MANDATORY** under `read_only: true` - - Optional bind: host `models` → `/data/models` - -2. **Verify volumes exist:** - ```bash - docker volume ls | grep hackolade-studio - ``` - -3. **Check volume mounts in running containers:** - ```bash - docker inspect | grep -A 10 Mounts - ``` - -4. **Review the warning message** - The CLI will indicate which specific mount is missing and what it's used for. - -**Important:** A single `/data` volume plus `/tmp` tmpfs replaces the older multi-volume layout (`/home/hackolade/.config`, separate logs/output volumes). Migrate by mounting your persistent state at `/data`. - -### License Validation Failed +Offline validation and license details: [license-validation.md](./license-validation.md). -- Make sure you're using the same image tag for getting UUID and validating -- Check that you're using a floating license key (not a workstation license) -- Ensure the license has available seats -- Verify secret files exist and have correct permissions +## Compose examples -### Secret File Not Found - -If Docker Compose can't find your secret files: - -1. Check the file paths in `compose.yml` match your actual file locations (note: `${HOME}/Downloads/` is just an example - use your actual paths) -2. Ensure the files exist at the paths specified in your `compose.yml`: - ```bash - # Example paths - adjust to match your compose.yml secrets section - ls -la ${HOME}/Downloads/license-key.txt - ls -la ${HOME}/Downloads/LicenseFile.xml - ``` -3. Verify file permissions (adjust paths to match your compose.yml): - ```bash - chmod 600 ${HOME}/Downloads/license-key.txt - chmod 600 ${HOME}/Downloads/LicenseFile.xml - ``` - -### Image Not Found - -If you get "image not found" errors: - -1. **If using Docker Compose**, pull the image: - ```bash - docker compose pull - ``` - -2. **If using Docker CLI directly**, pull the image explicitly with a version tag (the `latest` tag is not available): - ```bash - docker pull hackolade/hck-cli:8.12.7 - ``` - -3. Check available tags on [Docker Hub](https://hub.docker.com/r/hackolade/hck-cli/tags) - -4. Verify your Docker Hub access (the image may require authentication) - -5. If you need an intermediate release with plugin updates, update the image tag in your `compose.yml` (or use `docker pull` with the date-based tag): - ```bash - docker pull hackolade/hck-cli:8.12.7-2026-08-07 - ``` - -### Platform/Architecture Verification - -To verify that Docker is using the correct architecture for your platform: - -**Check your system architecture:** -```bash -# macOS/Linux -uname -m - -# Expected outputs: -# - x86_64 (Intel Macs, Linux AMD64) -# - arm64 (Apple Silicon Macs, Linux ARM64) -``` - -**Verify the pulled image architecture:** -```bash -docker image inspect hackolade/hck-cli:8.12.7 | grep Architecture -``` +| File | Use when | +| --- | --- | +| [`compose.yml`](../compose.yml) | Local use — minimal setup | +| [`compose.hardened.yml`](../compose.hardened.yml) | Production / CI — read-only rootfs, `cap_drop: ALL`, `/tmp` tmpfs | -**macOS Silicon users:** If you see `amd64` instead of `arm64`, Docker may be using emulation. To force ARM64 architecture: ```bash -docker pull --platform linux/arm64 hackolade/hck-cli:8.12.7 -``` - -Or in your `compose.yml`, specify the platform: -```yaml -services: - hck-cli: - image: hackolade/hck-cli:8.12.7 - platform: linux/arm64 # For Apple Silicon - # platform: linux/amd64 # For Intel/AMD +docker compose -f compose.hardened.yml run --rm hck-cli version ``` -**Note:** Docker Desktop for Mac automatically selects the correct architecture, so manual platform specification is usually not needed. - - - -## Next steps +## Storage layout -- Read [license-validation.md](./license-validation.md) for detailed license validation instructions -- **Need to install custom TLS certificates?** See [custom-certificates.md](./custom-certificates.md) for instructions on installing custom certificates in containers -- **Need to build a custom image?** See [getting-started.md](./getting-started.md) for instructions on building your own image with selected plugins -- Read [build.md](./build.md) for advanced build configurations -- Check the [Hackolade CLI documentation](https://hackolade.com/help/CommandLineInterface.html) for all available commands -- See [interactive-sessions.md](./interactive-sessions.md) for debugging and development workflows +Runtime writes go to **only two places**: -## Quick reference +| Mount | Purpose | +| --- | --- | +| `/data` | License state (`/data/app`), models, output, logs, settings | +| `/tmp` | Sockets, caches, scratch (use tmpfs when `read_only: true`) | -### Docker Compose Commands +The container runs as UID **1000**, GID **1001** by default. -```bash -# Pull the image (pulls the version specified in compose.yml) -docker compose pull +## Image tags -# Check version -docker compose run --rm hck-cli version - -# Get computer ID -docker compose run --rm showComputerIdForOfflineValidation +| Tag | Meaning | +| --- | --- | +| `hackolade/hck-cli:8.12.7` | Current Hackolade Studio release | +| `hackolade/hck-cli:8.12.7-2026-08-07` | Example intermediate tag (plugin updates on the current release) | -# Validate license (online) -docker compose run --rm validateKeyOnline +Update the `image:` line in your compose file, then `docker compose pull`. -# Validate license (offline) -docker compose run --rm validateKeyOffline +## Production and Kubernetes -# Run any CLI command -docker compose run --rm hck-cli COMMAND [OPTIONS] -``` +- **Docker Compose (restricted profile):** [`compose.hardened.yml`](../compose.hardened.yml) +- **Kubernetes Jobs:** [`k8s/`](../k8s/) — see [`k8s/README.md`](../k8s/README.md) +- **Private CAs:** [custom-certificates.md](./custom-certificates.md) -### Docker CLI Commands +## Docker CLI (without Compose) ```bash -# Pull the image (always specify a version tag) -docker pull hackolade/hck-cli:8.12.7 - -# Create volumes docker volume create hackolade-studio-data -# Run command -docker run --rm --read-only \ - --user 1000:1001 \ +docker run --rm \ -v hackolade-studio-data:/data \ - -v ${PWD}/models:/data/models \ - --tmpfs /tmp:rw,size=1g,mode=1777 \ - hackolade/hck-cli:8.12.7 COMMAND + -v "${PWD}/models:/data/models" \ + hackolade/hck-cli:8.12.7 version ``` -## Kubernetes (restricted / read-only rootfs) +For read-only rootfs, add `--read-only`, `--tmpfs /tmp:rw,size=1g,mode=1777`, `--user 1000:1001`, and `--cap-drop=ALL` — or use `compose.hardened.yml` as the reference. -Example manifests live in [`k8s/`](../k8s/). They mirror `compose.hardened.yml`: `readOnlyRootFilesystem`, non-root, dropped capabilities, a **PVC at `/data`**, and a **memory `emptyDir` at `/tmp`**. +## Troubleshooting -| Manifest | Purpose | +| Problem | Check | | --- | --- | -| [`k8s/hck-cli-job.yaml`](../k8s/hck-cli-job.yaml) | Smoke test (`version`) with PVC + `/tmp` emptyDir | -| [`k8s/hck-cli-job-openshift.yaml`](../k8s/hck-cli-job-openshift.yaml) | Same, for OpenShift `restricted-v2` (arbitrary UID, `fsGroup: 0`) | -| [`k8s/hck-cli-gendoc-job.yaml`](../k8s/hck-cli-gendoc-job.yaml) | Generate documentation from a model on the PVC | - -Apply the standard restricted example: +| Permission denied on `./models` | `chown -R 1000:1001 ./models` | +| Fails under `read_only: true` | Mount writable `/tmp` (tmpfs) | +| License validation fails | Same image tag for UUID + validation; floating seat available | +| Secret not found | Paths in `compose.yml` `secrets:` match files on disk | -```bash -kubectl apply -f k8s/hck-cli-job.yaml -kubectl logs job/hck-cli-version -``` - -Minimal Job excerpt (full file includes the PVC): - -```yaml -apiVersion: batch/v1 -kind: Job -metadata: - name: hck-cli-version - labels: - pod-security.kubernetes.io/enforce: restricted -spec: - template: - metadata: - labels: - pod-security.kubernetes.io/enforce: restricted - spec: - restartPolicy: Never - automountServiceAccountToken: false - securityContext: - runAsNonRoot: true - runAsUser: 1000 - runAsGroup: 1001 - fsGroup: 0 - seccompProfile: - type: RuntimeDefault - volumes: - - name: data - persistentVolumeClaim: - claimName: hck-cli-data - - name: tmp - emptyDir: - medium: Memory - sizeLimit: 1Gi - containers: - - name: hck-cli - image: hackolade/hck-cli:8.12.7 - args: ["version"] - securityContext: - allowPrivilegeEscalation: false - readOnlyRootFilesystem: true - capabilities: - drop: ["ALL"] - volumeMounts: - - name: data - mountPath: /data - - name: tmp - mountPath: /tmp -``` - -See [`k8s/README.md`](../k8s/README.md) for OpenShift and genDoc variants. - -## Backward compatibility with other images - -For users migrating from the `hackolade/studio` image or custom-built images that use `startup.sh` as the entrypoint, this image maintains backward compatibility by including the `startup.sh` and `show-computer-id.sh` scripts. - -You can override the entrypoint to use these scripts if needed: - -```bash -# Use show-computer-id.sh script (alternative to getComputerId command) -docker run --rm --entrypoint show-computer-id.sh hackolade/hck-cli:8.12.7 - -# Use startup.sh script (alternative to direct hck-cli entrypoint) -docker run --rm --entrypoint startup.sh hackolade/hck-cli:8.12.7 COMMAND [OPTIONS] -``` +## See also -**Note:** While these scripts are available for compatibility, the recommended approach is to use the `hck-cli` binary directly as the entrypoint, which provides better performance and simpler usage. +- [License validation](./license-validation.md) +- [Custom TLS certificates](./custom-certificates.md) +- [Build your own image](./getting-started.md) +- [Hackolade CLI command reference](https://hackolade.com/help/CommandLineInterface.html) diff --git a/Studio/k8s/README.md b/Studio/k8s/README.md index 8797087..c8380ab 100644 --- a/Studio/k8s/README.md +++ b/Studio/k8s/README.md @@ -1,20 +1,40 @@ -# Kubernetes examples for hackolade/hck-cli -# -# All manifests follow the Kubernetes Restricted Pod Security Standard and match -# compose.hardened.yml: read-only root filesystem, dropped capabilities, non-root -# user, persistent storage at /data, and a memory-backed emptyDir at /tmp. -# -# Files: -# hck-cli-job.yaml — smoke test (version) with PVC + /tmp emptyDir -# hck-cli-job-openshift.yaml — same, but for OpenShift restricted-v2 (arbitrary UID) -# hck-cli-gendoc-job.yaml — generate documentation from a model on the PVC -# -# Apply (pick the manifest that matches your platform): -# kubectl apply -f hck-cli-job.yaml -# kubectl apply -f hck-cli-job-openshift.yaml -# kubectl apply -f hck-cli-gendoc-job.yaml -# -# Prerequisites: -# - A validated license stored on the /data PVC (run validateKey once via a Job -# or copy license state from a Docker Compose volume). -# - For genDoc: place a model at /data/models/smoke.hck.json on the PVC. +# Kubernetes examples for `hackolade/hck-cli` + +Job manifests that match [`compose.hardened.yml`](../compose.hardened.yml): read-only root filesystem, non-root user, dropped capabilities, **PVC at `/data`**, and **memory `emptyDir` at `/tmp`**. + +Pin the image tag in each manifest (default: `hackolade/hck-cli:8.12.7`). + +## Manifests + +| File | Purpose | +| --- | --- | +| [`hck-cli-job.yaml`](./hck-cli-job.yaml) | Smoke test — runs `version` | +| [`hck-cli-job-openshift.yaml`](./hck-cli-job-openshift.yaml) | Same, for OpenShift `restricted-v2` (arbitrary UID) | +| [`hck-cli-gendoc-job.yaml`](./hck-cli-gendoc-job.yaml) | Example `genDoc` using a model on the PVC | + +## Quick test + +```bash +kubectl apply -f hck-cli-job.yaml +kubectl wait --for=condition=complete job/hck-cli-version --timeout=120s +kubectl logs job/hck-cli-version +``` + +## Before you run a real command + +1. **License** — validate once and persist state on the PVC (easiest: run [`compose.yml`](../compose.yml) locally, then reuse the volume data, or run a one-off validation Job). +2. **Models** — for `genDoc`, place a `.hck.json` file under `/data/models/` on the PVC. +3. **Storage class** — edit the PVC in the manifest if your cluster needs a specific `storageClassName`. + +## Writable mounts + +| Mount | Backing | Holds | +| --- | --- | --- | +| `/data` | PVC | License state (`/data/app`), models, output, logs | +| `/tmp` | memory `emptyDir` | Sockets, caches, scratch (required when `readOnlyRootFilesystem: true`) | + +## See also + +- [Getting started with hck-cli](../doc/getting-started-hck-cli.md) +- [License validation](../doc/license-validation.md) +- [Custom TLS certificates](../doc/custom-certificates.md) From 4c828d4cfe865df70f181ac499740f4055a0d2c0 Mon Sep 17 00:00:00 2001 From: "ugo.bechameil" Date: Fri, 7 Aug 2026 19:59:07 +0200 Subject: [PATCH 5/5] docs(hck-cli): surface consolidated /data + /tmp and hardened profile Document that all hck-cli deployments use the same two write paths regardless of read-only rootfs. Align compose.yml with /tmp tmpfs, lead getting started with runtime model and deployment profiles, and promote hardened Compose/K8s. Co-authored-by: Cursor --- README.md | 23 ++++--- Studio/README.md | 26 ++++++-- Studio/compose.hardened.yml | 13 ++-- Studio/compose.yml | 19 ++++-- Studio/doc/getting-started-hck-cli.md | 92 ++++++++++++++------------- Studio/k8s/README.md | 24 +++---- 6 files changed, 115 insertions(+), 82 deletions(-) diff --git a/README.md b/README.md index b530c79..4984c66 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,26 @@ # Running Hackolade CLI in Docker -This repository provides **ready-to-use examples** for the pre-built [`hackolade/hck-cli`](https://hub.docker.com/r/hackolade/hck-cli/tags) image: Hackolade Studio CLI, all target plugins, and a hardened runtime layout (`/data` + `/tmp`) — no build step required. +This repository provides **ready-to-use examples** for the pre-built [`hackolade/hck-cli`](https://hub.docker.com/r/hackolade/hck-cli/tags) image: Hackolade Studio CLI, all target plugins, no build step. ![Docker Image Version (latest by date)](https://img.shields.io/docker/v/hackolade/hck-cli) **Start here:** [Getting started with hackolade/hck-cli](./Studio/doc/getting-started-hck-cli.md) -The [`Studio/`](./Studio) folder includes: +## Runtime model -- [`compose.yml`](./Studio/compose.yml) — simple local Compose example -- [`compose.hardened.yml`](./Studio/compose.hardened.yml) — read-only rootfs, dropped capabilities (Kubernetes Restricted parity) -- [`k8s/`](./Studio/k8s/) — Job manifests with PVC at `/data` and memory `emptyDir` at `/tmp` +All examples use the **same two write paths** (whether or not the root filesystem is read-only): -## Custom-built images (legacy runtime) +- **`/data`** — persistent volume or PVC (license, models, output, logs) +- **`/tmp`** — tmpfs / memory emptyDir (ephemeral scratch) -If you need a custom plugin set or a bespoke image, you can still build on the [`hackolade/studio`](https://hub.docker.com/r/hackolade/studio/tags) runtime base image. That path requires a build step and uses the legacy `/home/hackolade/Documents/*` layout. +## Examples in [`Studio/`](./Studio) -See [Building your own image](./Studio/doc/getting-started.md) and [build.md](./Studio/doc/build.md). +| File | Profile | +| --- | --- | +| [`compose.yml`](./Studio/compose.yml) | Local — consolidated `/data` + `/tmp` | +| [`compose.hardened.yml`](./Studio/compose.hardened.yml) | **Hardened** — same mounts + read-only rootfs, dropped caps (CI / production) | +| [`k8s/`](./Studio/k8s/) | **Kubernetes** — same mounts + Restricted Pod Security Standard | + +## Custom-built images (legacy) + +Build on [`hackolade/studio`](https://hub.docker.com/r/hackolade/studio/tags) if you need a custom plugin set. That path uses the legacy `/home/hackolade/Documents/*` layout — see [getting-started.md](./Studio/doc/getting-started.md). diff --git a/Studio/README.md b/Studio/README.md index b015baf..ebb16f4 100644 --- a/Studio/README.md +++ b/Studio/README.md @@ -12,9 +12,23 @@ The instructions below assume Docker is [installed](https://www.docker.com/get-s Use the pre-built [`hackolade/hck-cli`](https://hub.docker.com/r/hackolade/hck-cli/tags) image — Hackolade Studio CLI with all plugins, no build step: -**[Getting started with hackolade/hck-cli](./doc/getting-started-hck-cli.md)** +**[Getting started with hackolade/hck-cli](./doc/getting-started-hck-cli.md)** — consolidated writes to `/data` + `/tmp`, hardened Compose, and Kubernetes examples. -Includes [`compose.yml`](./compose.yml), [`compose.hardened.yml`](./compose.hardened.yml) (read-only rootfs), and [`k8s/`](./k8s/) Job examples. +```bash +# Recommended baseline for CI / production (read-only rootfs, same write layout) +docker compose -f compose.hardened.yml run --rm hck-cli version +``` + +## Runtime model + +Every `hackolade/hck-cli` deployment uses **two writable mounts only**: + +| Mount | Purpose | +| --- | --- | +| `/data` | License state, models, output, logs (persistent volume or PVC) | +| `/tmp` | Sockets, caches, scratch (tmpfs / memory emptyDir) | + +[`compose.yml`](./compose.yml) and [`compose.hardened.yml`](./compose.hardened.yml) share this layout. Hardened adds read-only root filesystem, dropped capabilities, and non-root execution — the profile used in [`k8s/`](./k8s/) as well. ## Build your own image (advanced) @@ -22,11 +36,11 @@ Need a custom plugin set or Dockerfile based on [`hackolade/studio`](https://hub ## Repository structure -Primary examples use the pre-built **`hackolade/hck-cli`** image: +Primary examples use the pre-built **`hackolade/hck-cli`** image (same `/data` + `/tmp` write layout in every profile): -- [compose.yml](compose.yml): simple local Compose example -- [compose.hardened.yml](compose.hardened.yml): read-only rootfs, `/data` + `/tmp` tmpfs -- [k8s/](k8s/): Kubernetes Job manifests (PVC + memory emptyDir) +- [compose.yml](compose.yml): local Compose — consolidated mounts, writable rootfs +- [compose.hardened.yml](compose.hardened.yml): **hardened** — same mounts + read-only rootfs, `cap_drop: ALL` +- [k8s/](k8s/): **Kubernetes** Jobs — same mounts + Restricted Pod Security Standard Custom-build path (legacy layout on `hackolade/studio`): diff --git a/Studio/compose.hardened.yml b/Studio/compose.hardened.yml index 2fa617f..5810720 100644 --- a/Studio/compose.hardened.yml +++ b/Studio/compose.hardened.yml @@ -9,20 +9,21 @@ # Hardened Docker Compose example for hackolade/hck-cli. # -# Matches how the image runs under the Kubernetes Restricted Pod Security Standard -# and OpenShift restricted-v2 SCC: +# Same consolidated write layout as compose.yml (/data + /tmp). This file adds the +# security profile expected in CI, production, and Kubernetes Restricted: # # - read-only root filesystem # - all capabilities dropped, no privilege escalation # - non-root user (1000:1001 by default) -# - exactly two writable mounts: -# /data persistent volume — license state, logs, models, output, settings -# /tmp tmpfs — sockets, caches, scratch (discarded when the container exits) +# +# Writable mounts (always the same two paths): +# /data persistent volume — license state, logs, models, output, settings +# /tmp tmpfs — sockets, caches, scratch # # Usage: # docker compose -f compose.hardened.yml run --rm hck-cli version # -# For local development without these constraints, use compose.yml instead. +# For the same /data + /tmp layout without read-only rootfs, use compose.yml. # For Kubernetes manifests with a PVC, see k8s/hck-cli-job.yaml. # Documentation: doc/getting-started-hck-cli.md diff --git a/Studio/compose.yml b/Studio/compose.yml index 9c3728a..86bc809 100644 --- a/Studio/compose.yml +++ b/Studio/compose.yml @@ -10,13 +10,16 @@ # Example Docker Compose file for the pre-built hackolade/hck-cli image from Docker Hub. # The image includes Hackolade Studio and all plugins — ready to use without a build step. # -# For complete documentation and usage instructions, see: doc/getting-started-hck-cli.md +# Runtime writes are consolidated to exactly two mounts (same layout as compose.hardened.yml +# and the k8s/ manifests — only the security profile differs here): +# /data persistent volume — license state, logs, models, output, settings +# /tmp tmpfs — sockets, caches, scratch # -# If you are building your own image using hackolade/studio, use docker-compose.yml instead. -# See doc/getting-started.md for building instructions. +# For read-only root filesystem, dropped capabilities, and Kubernetes Restricted parity, +# use compose.hardened.yml instead. # -# For Kubernetes Restricted / OpenShift restricted-v2 parity (read-only root filesystem, -# dropped capabilities, /data volume + /tmp tmpfs), use compose.hardened.yml instead. +# Documentation: doc/getting-started-hck-cli.md +# Custom builds on hackolade/studio: docker-compose.yml + doc/getting-started.md services: # Run a CLI command (defaults to version). @@ -33,10 +36,12 @@ services: restart: 'no' # network_mode: 'none' volumes: - # Mandatory: license state, logs, output, settings, and options live under /data. + # Persistent state — license, logs, models, output (see doc/getting-started-hck-cli.md). - hackolade-studio-data:/data - # Models from the host; remove this line to keep models on the named volume instead. - ${PWD}/models:/data/models + tmpfs: + # Ephemeral scratch — same consolidated layout as compose.hardened.yml and k8s/. + - /tmp:rw,size=1g,mode=1777 showComputerIdForOfflineValidation: extends: hck-cli diff --git a/Studio/doc/getting-started-hck-cli.md b/Studio/doc/getting-started-hck-cli.md index 6267d74..18e5a39 100644 --- a/Studio/doc/getting-started-hck-cli.md +++ b/Studio/doc/getting-started-hck-cli.md @@ -4,71 +4,79 @@ Ready-to-use Docker image: Hackolade Studio CLI, all target plugins, no build st ![Docker Image Version (latest by date)](https://img.shields.io/docker/v/hackolade/hck-cli) +## Runtime model (all deployments) + +Every `hackolade/hck-cli` container uses the **same consolidated write layout** — whether you enable a read-only root filesystem or not. Runtime state is not scattered under `/home/hackolade/...` anymore. + +**Exactly two writable locations:** + +| Mount | Backing | Holds | +| --- | --- | --- | +| **`/data`** | Named volume or PVC | License state (`/data/app`), models, output, logs, settings | +| **`/tmp`** | tmpfs or memory `emptyDir` | Sockets, caches, scratch (ephemeral) | + +Everything persistent lives under **`/data`**. Everything transient goes to **`/tmp`**. + +This is the same layout in [`compose.yml`](../compose.yml), [`compose.hardened.yml`](../compose.hardened.yml), and the [`k8s/`](../k8s/) Job manifests — only the **security profile** changes. + +## Deployment profiles + +| Profile | Compose / manifest | Read-only rootfs | Extra hardening | +| --- | --- | --- | --- | +| **Local** | [`compose.yml`](../compose.yml) | No | Same `/data` + `/tmp` mounts | +| **Hardened** (recommended for CI / production) | [`compose.hardened.yml`](../compose.hardened.yml) | Yes | `cap_drop: ALL`, non-root, no privilege escalation | +| **Kubernetes** | [`k8s/hck-cli-job.yaml`](../k8s/hck-cli-job.yaml) | Yes | Same as hardened Compose (Restricted Pod Security Standard) | + +```bash +# Hardened smoke test (recommended baseline for pipelines) +docker compose -f compose.hardened.yml run --rm hck-cli version +``` + +OpenShift arbitrary UID: [`compose.hardened.yml`](../compose.hardened.yml) (`hck-cli-arbitrary-uid`) or [`k8s/hck-cli-job-openshift.yaml`](../k8s/hck-cli-job-openshift.yaml). + ## Before you start - **Floating license only** — workstation licenses do not work in Docker. - **Pin a version tag** — `latest` is not published. Example: `hackolade/hck-cli:8.12.7`. Weekly plugin refreshes may appear as `8.12.7-YYYY-MM-DD` on the [current release only](https://hub.docker.com/r/hackolade/hck-cli/tags). - **Re-validate when the image tag changes** — license state is tied to the image UUID. -- **Two writable mounts** — persistent `/data` plus writable `/tmp` (tmpfs in hardened setups). +- **Mount `/data` and `/tmp` on every run** — required when `read_only: true`; use the same layout even when the root filesystem is writable. -Need a custom plugin set or your own Dockerfile? See [getting-started.md](./getting-started.md) (build on `hackolade/studio`). +Need a custom plugin set or your own Dockerfile? See [getting-started.md](./getting-started.md) (legacy `hackolade/studio` build path). -## Quick start (Docker Compose) +## Quick start -1. Copy [`compose.yml`](../compose.yml) and create a models folder: +1. Copy a compose file and create a models folder: ```bash -cp compose.yml . +cp compose.hardened.yml compose.local.yml # or compose.yml for a minimal local run mkdir -p ./models ``` 2. Pull and check the image: ```bash -docker compose pull -docker compose run --rm hck-cli version +docker compose -f compose.local.yml pull +docker compose -f compose.local.yml run --rm hck-cli version ``` -3. Validate your license (online example — adjust secret paths in `compose.yml`): +3. Validate your license (online — adjust secret paths in the compose file): ```bash echo "YOUR-FLOATING-LICENSE-KEY" > ~/license-key.txt chmod 600 ~/license-key.txt -docker compose run --rm validateKeyOnline +docker compose -f compose.local.yml run --rm validateKeyOnline ``` 4. Run a command: ```bash -docker compose run --rm hck-cli genDoc \ +docker compose -f compose.local.yml run --rm hck-cli genDoc \ --format=HTML \ --model /data/models/my-model.hck.json \ --doc /data/output/doc ``` -Offline validation and license details: [license-validation.md](./license-validation.md). - -## Compose examples - -| File | Use when | -| --- | --- | -| [`compose.yml`](../compose.yml) | Local use — minimal setup | -| [`compose.hardened.yml`](../compose.hardened.yml) | Production / CI — read-only rootfs, `cap_drop: ALL`, `/tmp` tmpfs | - -```bash -docker compose -f compose.hardened.yml run --rm hck-cli version -``` - -## Storage layout - -Runtime writes go to **only two places**: - -| Mount | Purpose | -| --- | --- | -| `/data` | License state (`/data/app`), models, output, logs, settings | -| `/tmp` | Sockets, caches, scratch (use tmpfs when `read_only: true`) | - -The container runs as UID **1000**, GID **1001** by default. +Offline validation: [license-validation.md](./license-validation.md). ## Image tags @@ -79,37 +87,35 @@ The container runs as UID **1000**, GID **1001** by default. Update the `image:` line in your compose file, then `docker compose pull`. -## Production and Kubernetes - -- **Docker Compose (restricted profile):** [`compose.hardened.yml`](../compose.hardened.yml) -- **Kubernetes Jobs:** [`k8s/`](../k8s/) — see [`k8s/README.md`](../k8s/README.md) -- **Private CAs:** [custom-certificates.md](./custom-certificates.md) - ## Docker CLI (without Compose) +Same two-mount layout: + ```bash docker volume create hackolade-studio-data docker run --rm \ -v hackolade-studio-data:/data \ -v "${PWD}/models:/data/models" \ + --tmpfs /tmp:rw,size=1g,mode=1777 \ hackolade/hck-cli:8.12.7 version ``` -For read-only rootfs, add `--read-only`, `--tmpfs /tmp:rw,size=1g,mode=1777`, `--user 1000:1001`, and `--cap-drop=ALL` — or use `compose.hardened.yml` as the reference. +Hardened flags (`--read-only`, `--user 1000:1001`, `--cap-drop=ALL`): see [`compose.hardened.yml`](../compose.hardened.yml). ## Troubleshooting | Problem | Check | | --- | --- | | Permission denied on `./models` | `chown -R 1000:1001 ./models` | -| Fails under `read_only: true` | Mount writable `/tmp` (tmpfs) | +| Fails with read-only rootfs | Writable `/tmp` tmpfs is mounted | | License validation fails | Same image tag for UUID + validation; floating seat available | -| Secret not found | Paths in `compose.yml` `secrets:` match files on disk | +| Secret not found | Paths in compose `secrets:` match files on disk | ## See also - [License validation](./license-validation.md) -- [Custom TLS certificates](./custom-certificates.md) +- [Custom TLS certificates](./custom-certificates.md) (read-only PEM mounts — works with hardened / K8s) +- [Kubernetes examples](../k8s/README.md) - [Build your own image](./getting-started.md) - [Hackolade CLI command reference](https://hackolade.com/help/CommandLineInterface.html) diff --git a/Studio/k8s/README.md b/Studio/k8s/README.md index c8380ab..0721cf4 100644 --- a/Studio/k8s/README.md +++ b/Studio/k8s/README.md @@ -1,6 +1,13 @@ # Kubernetes examples for `hackolade/hck-cli` -Job manifests that match [`compose.hardened.yml`](../compose.hardened.yml): read-only root filesystem, non-root user, dropped capabilities, **PVC at `/data`**, and **memory `emptyDir` at `/tmp`**. +Same **consolidated write layout** as [`compose.yml`](../compose.yml) and [`compose.hardened.yml`](../compose.hardened.yml): + +| Mount | Backing | Holds | +| --- | --- | --- | +| `/data` | PVC | License state, models, output, logs | +| `/tmp` | memory `emptyDir` | Scratch (required with `readOnlyRootFilesystem`) | + +These manifests add the **hardened profile**: read-only root filesystem, non-root, dropped capabilities (Kubernetes **Restricted** Pod Security Standard). Pin the image tag in each manifest (default: `hackolade/hck-cli:8.12.7`). @@ -22,19 +29,12 @@ kubectl logs job/hck-cli-version ## Before you run a real command -1. **License** — validate once and persist state on the PVC (easiest: run [`compose.yml`](../compose.yml) locally, then reuse the volume data, or run a one-off validation Job). -2. **Models** — for `genDoc`, place a `.hck.json` file under `/data/models/` on the PVC. -3. **Storage class** — edit the PVC in the manifest if your cluster needs a specific `storageClassName`. - -## Writable mounts - -| Mount | Backing | Holds | -| --- | --- | --- | -| `/data` | PVC | License state (`/data/app`), models, output, logs | -| `/tmp` | memory `emptyDir` | Sockets, caches, scratch (required when `readOnlyRootFilesystem: true`) | +1. **License** — validate once and persist state on the PVC (easiest: run Compose locally, then reuse volume data). +2. **Models** — for `genDoc`, place a `.hck.json` under `/data/models/` on the PVC. +3. **Storage class** — edit the PVC if your cluster needs a specific `storageClassName`. ## See also -- [Getting started with hck-cli](../doc/getting-started-hck-cli.md) +- [Getting started with hck-cli](../doc/getting-started-hck-cli.md) — runtime model and deployment profiles - [License validation](../doc/license-validation.md) - [Custom TLS certificates](../doc/custom-certificates.md)