From 716f7ce3ef992aac86624fff2e0203cdc306aa70 Mon Sep 17 00:00:00 2001 From: "ugo.bechameil" Date: Thu, 22 Jan 2026 23:04:24 +0100 Subject: [PATCH 1/6] add documentation for the ready to use docker image --- Studio/README.md | 14 + Studio/compose.yml | 90 ++++ Studio/doc/getting-started-hck-cli.md | 678 ++++++++++++++++++++++++++ 3 files changed, 782 insertions(+) create mode 100644 Studio/compose.yml create mode 100644 Studio/doc/getting-started-hck-cli.md diff --git a/Studio/README.md b/Studio/README.md index 47beb92..9e8e13c 100644 --- a/Studio/README.md +++ b/Studio/README.md @@ -19,7 +19,21 @@ The purpose of running Hackolade Studio in a Docker container is to operate the The guide is designed to be understandable even if you've never used Docker before. +## 🎯 Using the Pre-built CLI Image (Recommended) +**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! + +**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 + +**Get started:** See our [Getting Started Guide for the Pre-built CLI Image](./doc/getting-started-hck-cli.md) for complete instructions. + +**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 ## 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): diff --git a/Studio/compose.yml b/Studio/compose.yml new file mode 100644 index 0000000..c5c73f9 --- /dev/null +++ b/Studio/compose.yml @@ -0,0 +1,90 @@ +# +# Copyright © 2016-2026 by IntegrIT S.A. dba Hackolade. All rights reserved. +# +# The copyright to the computer software herein is the property of IntegrIT S.A. +# The software may be used and/or copied only with the written permission of +# IntegrIT S.A. or in accordance with the terms and conditions stipulated in +# the agreement/contract under which the software has been supplied. +# + +# This file is an example of how to orchestrate the Hackolade CLI from a docker compose file +# leveraging our hck-cli docker image from Docker Hub +# This image contains the Hackolade Studio Release and all of the plugins already installed +# It's ready to be used. + +services: + # Run a cli command (default to version) + # Pay attention to file paths as they must be paths inside the containers + # If a file needs to be made available from the host or another container, use the volumes section to mount the file or folders + # This compose exposes different manners to provide the License key or LicenseFile.xml for offline validation + + # Example using online License key validation and the key stored in a secret file (file path from host) defined in the secrets section: + # + # docker compose run -t --rm validateKeyOnline + # docker compose run -t --rm hck-cli gendoc --format=HTML --model '/data/models/MongoDB/Yelp Challenge dataset.hck.json' --doc /data/output/doc-test --jsonSchema + hck-cli: &hck-cli + image: hackolade/hck-cli:8.8.5 + command: ["version"] + restart: 'no' + # network_mode: 'none' + volumes: + - hackolade-studio-app-data:/home/hackolade/.config + - hackolade-studio-logs:/data/logs + - ${PWD}/models:/data/models + # - hackolade-studio-options:/data/options + - hackolade-studio-output:/data/output + + showComputerIdForOfflineValidation: + extends: hck-cli + command: ["getComputerId"] + + # validateKeyOfflineFromFile: + # extends: hck-cli + # network_mode: 'none' + # command: + # - validateKey + # - --file + # - /data/LicenseFile.xml + # volumes: + # - $HOME/Downloads/LicenseFile.xml:/data/LicenseFile.xml + + # validateKeyOnlineFromFile: + # extends: hck-cli + # command: + # - validateKey + # - --key + # - /data/license-key.txt + # volumes: + # - $HOME/Downloads/license-key.txt:/data/license-key.txt + + + validateKeyOffline: + extends: hck-cli + network_mode: 'none' + command: ["validateKey"] + secrets: + - license_file + + validateKeyOnline: + extends: hck-cli + command: ["validateKey"] + network_mode: host + secrets: + - license_key + +volumes: + # This docker volume is mandatory if you want the licensing to work and be able to use the cli + hackolade-studio-app-data: + hackolade-studio-logs: + # This compose mounts the models folder from the host + # hackolade-studio-models: + # hackolade-studio-options: + hackolade-studio-output: + +secrets: # Don't change the name of the secrets as the cli is looking for them by name with these values by default + license_key: + # Expects the license key to be put as content of the file path defined in the file variable + file: ${HOME}/Downloads/license-key.txt + license_file: + # Expects the license file to be put as content of the file path defined in the file variable + file: ${HOME}/Downloads/LicenseFile.xml diff --git a/Studio/doc/getting-started-hck-cli.md b/Studio/doc/getting-started-hck-cli.md new file mode 100644 index 0000000..c192c21 --- /dev/null +++ b/Studio/doc/getting-started-hck-cli.md @@ -0,0 +1,678 @@ +# Getting Started with Hackolade CLI Docker Image + +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. + +![Docker Image Version (latest by date)](https://img.shields.io/docker/v/hackolade/hck-cli) + +## 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`) +- 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 starting from 8.8.5 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 M1/M2/M3 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 + +## 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.8.5` - Initial release version (starting from 8.8.5) +- `hackolade/hck-cli:8.8.5-YYYY-MM-DD` - Intermediate tags for plugin updates during the week (e.g., `8.8.5-2025-01-10`) + +**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. + +**Platform support:** +- ✅ **AMD64/x86_64** - Linux and Windows (Intel/AMD processors) +- ✅ **ARM64** - Linux ARM64 and **macOS Silicon** (Apple M1/M2/M3 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 **concurrent 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 (M1/M2/M3) 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 uses a simplified data structure with volumes mounted directly under `/data`: + +- `/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 + +**⚠️ MANDATORY:** The application data folder (`/home/hackolade/.config`) **MUST** be mounted as a volume. This volume is absolutely required for licensing and configuration to work properly. Without this volume mounted, the CLI will not function correctly. + +This structure reduces path length and simplifies volume management compared to the previous `/home/hackolade/Documents/...` structure. + +**Volume validation:** The CLI automatically validates that required volumes are properly mounted. If a required volume is missing, the CLI will display a warning message to help you identify and fix the issue before command execution fails. + +**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. Each command execution creates its own log folder, allowing you to trace problems to specific operations by date and command type. + +## Quick Start with Docker Compose + +The easiest way to use this image is with Docker Compose. We provide a `compose.yml` file that handles all the configuration. + +### Step 1: Set Up Your Compose File + +We provide a ready-to-use `compose.yml` file. You can either: + +**Option A: Copy the provided compose file** (recommended) + +Copy the [`compose.yml`](../compose.yml) file from this repository to your working directory: + +```bash +cp compose.yml /path/to/your/working/directory/ +``` + +**Option B: Create your own compose file** + +Create a `compose.yml` file in your working directory. See the [`compose.yml`](../compose.yml) file in this repository for a complete example. + +The compose file includes: +- `hck-cli` service - Main service for running CLI commands +- `showComputerIdForOfflineValidation` service - Gets computer ID for offline license validation +- `validateKeyOnline` service - Validates license online using Docker secrets +- `validateKeyOffline` service - Validates license offline using Docker secrets +- Volume definitions for app data, logs, models, and output +- Secret definitions for license key and license file + +### Step 2: Create Your Models Directory + +Create a directory for your model files: + +```bash +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): + +```bash +docker compose pull +``` + +This will pull the image version specified in your `compose.yml` file (`hackolade/hck-cli:8.8.5`). 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.8.5-2025-01-10`) and run `docker compose pull` again. + +### Step 4: Validate Your License + +Before using the CLI, you must validate your license. 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 your license key. 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., `12345678-1234-1234-1234-123456789abc`). + +**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 concurrent 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 +``` + +## 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 \ + -v hackolade-studio-app-data:/home/hackolade/.config \ + -v hackolade-studio-logs:/data/logs \ + -v ${PWD}/models:/data/models \ + -v hackolade-studio-output:/data/output \ + hackolade/hck-cli:8.8.5 COMMAND [OPTIONS] +``` + +### Create Required Volumes + +First, create the named volumes: + +```bash +docker volume create hackolade-studio-app-data +docker volume create hackolade-studio-logs +docker volume create hackolade-studio-output +``` + +### Example Commands + +**Check version:** +```bash +docker run --rm \ + -v hackolade-studio-app-data:/home/hackolade/.config \ + hackolade/hck-cli:8.8.5 version +``` + +**Get computer ID:** +```bash +docker run --rm \ + --entrypoint show-computer-id.sh \ + hackolade/hck-cli:8.8.5 +``` + +**Generate documentation:** +```bash +docker run --rm \ + -v hackolade-studio-app-data:/home/hackolade/.config \ + -v hackolade-studio-logs:/data/logs \ + -v ${PWD}/models:/data/models \ + -v hackolade-studio-output:/data/output \ + hackolade/hck-cli:8.8.5 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: + file: ${HOME}/Downloads/license-key.txt # Example path - use any path you prefer + license_file: + 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.8.5 validateKey +``` + +**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 +``` + +This ensures the container has no network access during offline validation. + +## Common Scenarios + +### Scenario 1: Generate Documentation + +```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: + +**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.8.5 -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.8.5 -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 user `hackolade` with UID 1000 and GID 1001 (data-modelers group). + +**Note:** Docker named volumes (like `hackolade-studio-app-data`) don't require permission changes on the host. + +### Volume Not Found + +If Docker says a volume doesn't exist, create it: + +```bash +docker volume create hackolade-studio-app-data +docker volume create hackolade-studio-logs +docker volume create hackolade-studio-output +``` + +Or let Docker Compose create them automatically on first run. + +### Volume Validation Warnings + +The CLI automatically checks for required volumes and will warn you if they're not properly mounted. If you see warnings about missing volumes: + +1. **Check your compose.yml or docker run command** - Ensure all required volumes are defined: + - `hackolade-studio-app-data` → `/home/hackolade/.config` ⚠️ **MANDATORY** - Required for licensing and configuration + - `hackolade-studio-logs` → `/data/logs` (recommended for log isolation) + - `hackolade-studio-output` → `/data/output` (required for output operations) + +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 volume is missing and what it's used for. + +**Important:** The `/home/hackolade/.config` volume is **MANDATORY** and must be mounted for the CLI to function. While the CLI will warn about missing volumes, operations will fail without the application data volume. For proper functionality and log isolation, mount all volumes as shown in the compose examples. + +### License Validation Failed + +- Make sure you're using the same image tag for getting UUID and validating +- Check that you're using a concurrent license key (not a workstation license) +- Ensure the license has available seats +- Verify secret files exist and have correct permissions + +### 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.8.5 + ``` + +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.8.5-2025-01-10 + ``` + +### 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.8.5 | 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.8.5 +``` + +Or in your `compose.yml`, specify the platform: +```yaml +services: + hck-cli: &hck-cli + image: hackolade/hck-cli:8.8.5 + platform: linux/arm64 # For Apple Silicon + # platform: linux/amd64 # For Intel/AMD +``` + +**Note:** Docker Desktop for Mac automatically selects the correct architecture, so manual platform specification is usually not needed. + +## Differences from Building Your Own Image + +| Feature | Pre-built Image (`hackolade/hck-cli`) | Building Your Own | +|---------|--------------------------------------|-------------------| +| 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) | Depends on build platform | +| 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 M1/M2/M3) 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 + +## Next Steps + +- Read [license-validation.md](./license-validation.md) for detailed license validation instructions +- Read [build.md](./build.md) if you need to build a custom image with specific plugins +- 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 + +## Quick Reference + +### Docker Compose Commands + +```bash +# Pull the image (pulls the version specified in compose.yml) +docker compose pull + +# Check version +docker compose run --rm hck-cli version + +# Get computer ID +docker compose run --rm showComputerIdForOfflineValidation + +# Validate license (online) +docker compose run --rm validateKeyOnline + +# Validate license (offline) +docker compose run --rm validateKeyOffline + +# Run any CLI command +docker compose run --rm hck-cli COMMAND [OPTIONS] +``` + +### Docker CLI Commands + +```bash +# Pull the image (always specify a version tag) +docker pull hackolade/hck-cli:8.8.5 + +# Create volumes +docker volume create hackolade-studio-app-data +docker volume create hackolade-studio-logs +docker volume create hackolade-studio-output + +# Run command +docker run --rm \ + -v hackolade-studio-app-data:/home/hackolade/.config \ + -v hackolade-studio-logs:/data/logs \ + -v ${PWD}/models:/data/models \ + -v hackolade-studio-output:/data/output \ + hackolade/hck-cli:8.8.5 COMMAND +``` + +## Important Notes + +- **Concurrent licenses only** - workstation 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.8.5` or intermediate tags like `8.8.5-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/*` + +## 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.8.5 + +# Use startup.sh script (alternative to direct hck-cli entrypoint) +docker run --rm --entrypoint startup.sh hackolade/hck-cli:8.8.5 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. From ddd561a8182114a98056dd82c8aae9d12bf7dadc Mon Sep 17 00:00:00 2001 From: "ugo.bechameil" Date: Thu, 22 Jan 2026 23:07:24 +0100 Subject: [PATCH 2/6] tweak wording --- Studio/doc/getting-started-hck-cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Studio/doc/getting-started-hck-cli.md b/Studio/doc/getting-started-hck-cli.md index c192c21..305d3ab 100644 --- a/Studio/doc/getting-started-hck-cli.md +++ b/Studio/doc/getting-started-hck-cli.md @@ -164,7 +164,7 @@ First, get the computer ID (UUID) that will be used to generate the offline lice docker compose run --rm showComputerIdForOfflineValidation ``` -Copy the UUID that's displayed (e.g., `12345678-1234-1234-1234-123456789abc`). +Copy the UUID that's displayed (e.g., `12345678-1234-1234-1234-123456789abc-docker`). Note that Docker images will have the `-docker` suffix in the UUID. **Step 4b: Generate the license file** From 06cb467ebb824d80d051ae197145061e0eb99309 Mon Sep 17 00:00:00 2001 From: "ugo.bechameil" Date: Thu, 22 Jan 2026 23:09:47 +0100 Subject: [PATCH 3/6] Use a real world example --- Studio/doc/getting-started-hck-cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Studio/doc/getting-started-hck-cli.md b/Studio/doc/getting-started-hck-cli.md index 305d3ab..98dbd4d 100644 --- a/Studio/doc/getting-started-hck-cli.md +++ b/Studio/doc/getting-started-hck-cli.md @@ -164,7 +164,7 @@ First, get the computer ID (UUID) that will be used to generate the offline lice docker compose run --rm showComputerIdForOfflineValidation ``` -Copy the UUID that's displayed (e.g., `12345678-1234-1234-1234-123456789abc-docker`). Note that Docker images will have the `-docker` suffix in the UUID. +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 a75b14501f813752e0219518adc349264546aff7 Mon Sep 17 00:00:00 2001 From: "ugo.bechameil" Date: Thu, 22 Jan 2026 23:12:43 +0100 Subject: [PATCH 4/6] Reorganize --- Studio/doc/getting-started-hck-cli.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/Studio/doc/getting-started-hck-cli.md b/Studio/doc/getting-started-hck-cli.md index 98dbd4d..b297402 100644 --- a/Studio/doc/getting-started-hck-cli.md +++ b/Studio/doc/getting-started-hck-cli.md @@ -4,6 +4,16 @@ This guide will help you get started with the **ready-to-use** Hackolade CLI Doc ![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: + +- **Concurrent licenses only** - workstation 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.8.5` or intermediate tags like `8.8.5-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/*` + ## What is This Image? The `hackolade/hck-cli` Docker image is a pre-built, production-ready image that includes: @@ -653,14 +663,6 @@ docker run --rm \ hackolade/hck-cli:8.8.5 COMMAND ``` -## Important Notes - -- **Concurrent licenses only** - workstation 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.8.5` or intermediate tags like `8.8.5-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/*` - ## 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. From ebc25e155ddd4f69b0017ad44036c57c57ed4bb0 Mon Sep 17 00:00:00 2001 From: "ugo.bechameil" Date: Fri, 23 Jan 2026 12:06:53 +0100 Subject: [PATCH 5/6] Update documentation and cross links --- Studio/compose.yml | 6 ++ Studio/doc/getting-started-hck-cli.md | 130 ++++++++++++++------------ Studio/doc/getting-started.md | 63 ++++++++++++- Studio/docker-compose.yml | 9 ++ 4 files changed, 143 insertions(+), 65 deletions(-) diff --git a/Studio/compose.yml b/Studio/compose.yml index c5c73f9..2a215a1 100644 --- a/Studio/compose.yml +++ b/Studio/compose.yml @@ -11,6 +11,12 @@ # leveraging our hck-cli docker image from Docker Hub # This image contains the Hackolade Studio Release and all of the plugins already installed # It's ready to be used. +# +# This compose.yml file is specifically designed for the pre-built hackolade/hck-cli image. +# For complete documentation and usage instructions, see: doc/getting-started-hck-cli.md +# +# If you are building your own image using hackolade/studio, use docker-compose.yml instead, +# which is designed for custom-built images. See doc/getting-started.md for building instructions. services: # Run a cli command (default to version) diff --git a/Studio/doc/getting-started-hck-cli.md b/Studio/doc/getting-started-hck-cli.md index b297402..40c1d01 100644 --- a/Studio/doc/getting-started-hck-cli.md +++ b/Studio/doc/getting-started-hck-cli.md @@ -8,11 +8,13 @@ This guide will help you get started with the **ready-to-use** Hackolade CLI Doc Before you begin, please note these critical requirements: -- **Concurrent licenses only** - workstation 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.8.5` or intermediate tags like `8.8.5-YYYY-MM-DD` for plugin updates +- **Concurrent licenses only**: workstation 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.8.5` or intermediate tags like `8.8.5-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/*` +- **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.8.5-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? @@ -23,28 +25,56 @@ The `hackolade/hck-cli` Docker image is a pre-built, production-ready image that - Ready to use immediately - no build step required **Key advantages:** -- ✅ No need to build your own image -- ✅ Versioned releases starting from 8.8.5 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 M1/M2/M3 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 +- No need to build your own image +- Versioned releases starting from 8.8.5 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) | Depends on build platform | +| 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.8.5` - Initial release version (starting from 8.8.5) -- `hackolade/hck-cli:8.8.5-YYYY-MM-DD` - Intermediate tags for plugin updates during the week (e.g., `8.8.5-2025-01-10`) +- `hackolade/hck-cli:8.8.5` : Initial release version (starting from 8.8.5) +- `hackolade/hck-cli:8.8.5-YYYY-MM-DD` -:Intermediate tags for plugin updates during the week (e.g., `8.8.5-2025-01-10`) **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.8.5-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 M1/M2/M3 chips) +- **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. @@ -57,7 +87,7 @@ Before you begin, make sure you have: 3. **Docker is running** (check by running `docker --version` in your terminal) 4. A **concurrent 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 (M1/M2/M3) without emulation overhead. Docker Desktop automatically selects the correct architecture. +**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 @@ -86,13 +116,15 @@ This structure reduces path length and simplifies volume management compared to The easiest way to use this image is with Docker Compose. We provide a `compose.yml` file that handles all the configuration. +**Important:** The [`compose.yml`](../compose.yml) file in this repository is specifically designed for the **pre-built `hackolade/hck-cli` image** and is tied to this documentation. It uses simplified data paths (`/data/*`) and the `hck-cli` binary entrypoint, which differ from compose files used with custom-built images. + ### Step 1: Set Up Your Compose File -We provide a ready-to-use `compose.yml` file. You can either: +We provide a ready-to-use `compose.yml` file specifically for the pre-built image. You can either: **Option A: Copy the provided compose file** (recommended) -Copy the [`compose.yml`](../compose.yml) file from this repository to your working directory: +Copy the [`compose.yml`](../compose.yml) file from this repository to your working directory. This compose file is specifically designed for the pre-built `hackolade/hck-cli` image and is documented in this guide: ```bash cp compose.yml /path/to/your/working/directory/ @@ -100,9 +132,9 @@ cp compose.yml /path/to/your/working/directory/ **Option B: Create your own compose file** -Create a `compose.yml` file in your working directory. See the [`compose.yml`](../compose.yml) file in this repository for a complete example. +Create a `compose.yml` file in your working directory. See the [`compose.yml`](../compose.yml) file in this repository for a complete example. Make sure to follow the structure documented in this guide. -The compose file includes: +The compose file (designed for the pre-built image) includes: - `hck-cli` service - Main service for running CLI commands - `showComputerIdForOfflineValidation` service - Gets computer ID for offline license validation - `validateKeyOnline` service - Validates license online using Docker secrets @@ -141,7 +173,7 @@ Use this method if your server has internet access. **Step 4a: Prepare your license key file** -Create a file containing your license key. 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: +Create a file containing your license key. 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) @@ -160,7 +192,7 @@ The compose file automatically: - 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. +**Note:** For online validation, you don't need to get the computer ID separately. The validation process handles it automatically. #### Offline License Validation @@ -188,11 +220,11 @@ Fill in the form: - **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. +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: +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) @@ -290,9 +322,7 @@ docker run --rm \ **Get computer ID:** ```bash -docker run --rm \ - --entrypoint show-computer-id.sh \ - hackolade/hck-cli:8.8.5 +docker run --rm hackolade/hck-cli:8.8.5 getComputerId ``` **Generate documentation:** @@ -315,19 +345,19 @@ docker run --rm \ 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 +- 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: + 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: + license_file: # Don't change the name of the secret! file: ${HOME}/Downloads/LicenseFile.xml # Example path - use any path you prefer ``` @@ -362,7 +392,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.8.5 validateKey + hackolade/hck-cli:8.8.5 validateKey --key ${LICENSE_KEY} ``` **Why secrets are better:** @@ -429,7 +459,7 @@ docker compose run --rm hck-cli compMod \ ## Retrieving Generated Files -After running commands, retrieve files from Docker volumes: +After running commands, retrieve files from Docker volumes (if you used named volumes): **Retrieve output files:** ```bash @@ -579,7 +609,7 @@ docker pull --platform linux/arm64 hackolade/hck-cli:8.8.5 Or in your `compose.yml`, specify the platform: ```yaml services: - hck-cli: &hck-cli + hck-cli: image: hackolade/hck-cli:8.8.5 platform: linux/arm64 # For Apple Silicon # platform: linux/amd64 # For Intel/AMD @@ -587,35 +617,13 @@ services: **Note:** Docker Desktop for Mac automatically selects the correct architecture, so manual platform specification is usually not needed. -## Differences from Building Your Own Image - -| Feature | Pre-built Image (`hackolade/hck-cli`) | Building Your Own | -|---------|--------------------------------------|-------------------| -| 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) | Depends on build platform | -| 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 M1/M2/M3) 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 ## Next Steps - Read [license-validation.md](./license-validation.md) for detailed license validation instructions -- Read [build.md](./build.md) if you need to build a custom image with specific plugins +- **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 diff --git a/Studio/doc/getting-started.md b/Studio/doc/getting-started.md index 295fe94..e49106b 100644 --- a/Studio/doc/getting-started.md +++ b/Studio/doc/getting-started.md @@ -28,8 +28,63 @@ Docker Compose is a tool that lets you define and run multiple containers using - You prefer configuration files over long command lines - You're working in a team (easier to share configuration) +### Compose File for Custom-Built Images +This guide uses [`docker-compose.yml`](../docker-compose.yml), which is specifically designed for **custom-built images** based on `hackolade/studio`. This compose file: +- Uses traditional data paths (`/home/hackolade/Documents/*`) +- References your custom-built image tag (`hackolade:latest`) +- Uses the `startup.sh` entrypoint +- Is documented in this guide +**Note:** If you want to use the pre-built `hackolade/hck-cli` image instead, use [`compose.yml`](../compose.yml) which is designed for the pre-built image. See [getting-started-hck-cli.md](./getting-started-hck-cli.md) for details. + +## Building Your Own vs. Pre-built Image + +Before you start, decide which approach fits your needs: + +| Feature | Building Your Own (`hackolade/studio`) | Pre-built Image (`hackolade/hck-cli`) | +|---------|----------------------------------------|--------------------------------------| +| Setup time | Requires build step | Instant (just pull) | +| Data paths | `/home/hackolade/Documents/*` | `/data/*` (simplified) | +| Entrypoint | `startup.sh` script | `hck-cli` binary | +| Updates | Rebuild image | Pull new version | +| Plugins | Select during build | All included | +| Architecture support | Depends on build platform | Multi-arch (AMD64 + ARM64) | +| Customization | Full control | Limited | + +**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 + +**📖 Ready-to-use pre-built image?** See the [Getting Started Guide for the Pre-built CLI Image](./getting-started-hck-cli.md) for complete instructions. + +**🔨 Need to build your own?** Continue with this guide to learn how to build a custom image with selected plugins. + +## ⚠️ Migration Notice for Existing Users + +If you are currently using a custom-built image based on `hackolade/studio` and have an existing `docker-compose.yml` file, **you must migrate to the new `compose.yml` structure** when using the pre-built `hackolade/hck-cli` image. + +**Key differences you need to update:** + +1. **Image reference**: Change from your custom image tag to `hackolade/hck-cli:8.8.5` (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` + - `/home/hackolade/Documents/HackoladeLogs` → `/data/logs` +3. **Entrypoint**: The pre-built image uses `hck-cli` binary directly (no `startup.sh` wrapper needed) +4. **Working directory**: Remove `-w /home/hackolade/Documents` as it's no longer needed + +**Reference compose file:** Use the [`compose.yml`](../compose.yml) file in this repository as your migration reference. This compose file is specifically designed for the pre-built image and documented in [getting-started-hck-cli.md](./getting-started-hck-cli.md). + +**If you continue building your own image:** Use the [`docker-compose.yml`](../docker-compose.yml) file in this repository, which is specifically designed for custom-built images. This compose file uses the traditional data paths (`/home/hackolade/Documents/*`) and is documented in this guide. ## Prerequisites @@ -89,7 +144,7 @@ mkdir -p ./models chown -R 1000:0 ./models ``` -The `docker-compose.yml` file (already in this repository) defines all the volumes for you. +The [`docker-compose.yml`](../docker-compose.yml) file (already in this repository) is specifically designed for custom-built images and defines all the volumes for you. @@ -119,7 +174,7 @@ Docker Compose doesn't build images directly, but you can still use the same Doc docker build --no-cache --pull -t hackolade:latest . ``` -**Note:** The `docker-compose.yml` file references `hackolade:latest`, so make sure your image has this exact tag. +**Note:** The [`docker-compose.yml`](../docker-compose.yml) file (designed for custom-built images) references `hackolade:latest`, so make sure your image has this exact tag. @@ -177,7 +232,7 @@ docker compose run --rm hackoladeStudioCLI validatekey \ This single command does both steps automatically by using `$(...)` to get the UUID inline. -**Note:** The `docker-compose.yml` file automatically handles all the volume mounts, so you don't need to specify them manually. +**Note:** The [`docker-compose.yml`](../docker-compose.yml) file (designed for custom-built images) automatically handles all the volume mounts, so you don't need to specify them manually. @@ -237,7 +292,7 @@ docker run --rm \ docker compose run --rm hackoladeStudioCLI COMMAND [OPTIONS] ``` -Much simpler! Docker Compose automatically handles all the volumes based on `docker-compose.yml`. +Much simpler! Docker Compose automatically handles all the volumes based on [`docker-compose.yml`](../docker-compose.yml), which is designed for custom-built images. **Example: Show help** ```bash diff --git a/Studio/docker-compose.yml b/Studio/docker-compose.yml index c1f4c27..db99470 100644 --- a/Studio/docker-compose.yml +++ b/Studio/docker-compose.yml @@ -1,3 +1,12 @@ +# This docker-compose.yml file is specifically designed for custom-built images +# based on hackolade/studio. It uses the traditional data paths (/home/hackolade/Documents/*) +# and startup.sh entrypoint. +# +# For complete documentation and usage instructions, see: doc/getting-started.md +# +# If you want to use the pre-built hackolade/hck-cli image instead, use compose.yml +# which is designed for the pre-built image. See doc/getting-started-hck-cli.md + services: hackoladeStudioCLI: image: hackolade:latest From b03cf5070f7b632a8100d93a96a4655cb81388a5 Mon Sep 17 00:00:00 2001 From: "ugo.bechameil" Date: Fri, 23 Jan 2026 12:17:00 +0100 Subject: [PATCH 6/6] tweak wording and formatting --- Studio/doc/getting-started-hck-cli.md | 28 ++++----- Studio/doc/getting-started.md | 88 +++++++++++++-------------- 2 files changed, 58 insertions(+), 58 deletions(-) diff --git a/Studio/doc/getting-started-hck-cli.md b/Studio/doc/getting-started-hck-cli.md index 40c1d01..7cf2472 100644 --- a/Studio/doc/getting-started-hck-cli.md +++ b/Studio/doc/getting-started-hck-cli.md @@ -4,7 +4,7 @@ This guide will help you get started with the **ready-to-use** Hackolade CLI Doc ![Docker Image Version (latest by date)](https://img.shields.io/docker/v/hackolade/hck-cli) -## ⚠️ Important Notes +## ⚠️ Important notes Before you begin, please note these critical requirements: @@ -16,7 +16,7 @@ Before you begin, please note these critical requirements: > **🚨 CRITICAL - Plugin Updates Policy:** Plugin updates between releases are **ONLY** available via intermediate tags from the **latest release** (e.g., `hackolade/hck-cli:8.8.5-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? +## 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`) @@ -34,7 +34,7 @@ The `hackolade/hck-cli` Docker image is a pre-built, production-ready image that - 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 +## Differences from building your own image | Feature | Pre-built Image (`hackolade/hck-cli`) | Building Your Own (hackolade/studio) | |---------|--------------------------------------|-------------------| @@ -43,7 +43,7 @@ The `hackolade/hck-cli` Docker image is a pre-built, production-ready image that | 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) | Depends on build platform | +| Architecture support | Multi-arch (AMD64 + ARM64) | AMD64/x86_64 only (Intel-based chips) | | Customization | Limited | Full control | **When to use the pre-built image:** @@ -59,7 +59,7 @@ The `hackolade/hck-cli` Docker image is a pre-built, production-ready image that - You have specific security requirements - See [build.md](./build.md) for instructions -## Image Availability +## 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. @@ -89,7 +89,7 @@ Before you begin, make sure you have: **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 +## Understanding the image structure ### Entrypoint @@ -112,7 +112,7 @@ This structure reduces path length and simplifies volume management compared to **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. Each command execution creates its own log folder, allowing you to trace problems to specific operations by date and command type. -## Quick Start with Docker Compose +## Quick start with Docker Compose The easiest way to use this image is with Docker Compose. We provide a `compose.yml` file that handles all the configuration. @@ -286,7 +286,7 @@ docker compose run --rm hck-cli forweng \ --outputtype jsonschema ``` -## Using Docker CLI Directly +## Using Docker CLI directly If you prefer using Docker CLI directly instead of Docker Compose, here's how: @@ -338,7 +338,7 @@ docker run --rm \ --doc /data/output/doc.html ``` -## Security Best Practices +## Security best practices ### Using Docker Secrets for License Keys @@ -413,7 +413,7 @@ validateKeyOffline: This ensures the container has no network access during offline validation. -## Common Scenarios +## Common scenarios ### Scenario 1: Generate Documentation @@ -457,7 +457,7 @@ docker compose run --rm hck-cli compMod \ --deltamodel=/data/output/delta.json ``` -## Retrieving Generated Files +## Retrieving generated files After running commands, retrieve files from Docker volumes (if you used named volumes): @@ -619,7 +619,7 @@ services: -## Next Steps +## Next steps - Read [license-validation.md](./license-validation.md) for detailed license validation instructions - **Need to build a custom image?** See [getting-started.md](./getting-started.md) for instructions on building your own image with selected plugins @@ -627,7 +627,7 @@ services: - 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 -## Quick Reference +## Quick reference ### Docker Compose Commands @@ -671,7 +671,7 @@ docker run --rm \ hackolade/hck-cli:8.8.5 COMMAND ``` -## Backward Compatibility with Other Images +## 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. diff --git a/Studio/doc/getting-started.md b/Studio/doc/getting-started.md index e49106b..dd4e726 100644 --- a/Studio/doc/getting-started.md +++ b/Studio/doc/getting-started.md @@ -1,10 +1,10 @@ # Getting Started with Hackolade Studio CLI in Docker -This guide will help you run Hackolade Studio CLI in Docker, whether you're new to Docker or an experienced user. We provide instructions using both **Docker CLI directly** and **Docker Compose** - choose the approach that works best for you. +This guide will help you run Hackolade Studio CLI in Docker, whether you're new to Docker or an experienced user. We provide instructions using both **Docker CLI directly** and **Docker Compose**. Choose the approach that works best for you. -## What is Docker? (A Simple Explanation) +## What is Docker? (A simple explanation) -Think of Docker as a way to package an application with everything it needs to run (like a shipping container). Instead of installing Hackolade Studio directly on your computer, you run it inside a "container" - an isolated environment that has all the necessary components pre-installed. +Think of Docker as a way to package an application with everything it needs to run (like a shipping container). Instead of installing Hackolade Studio directly on your computer, you run it inside a "container", an isolated environment that has all the necessary components pre-installed. **Key Docker concepts:** - **Image**: A template/blueprint for creating containers (like a recipe) @@ -28,7 +28,7 @@ Docker Compose is a tool that lets you define and run multiple containers using - You prefer configuration files over long command lines - You're working in a team (easier to share configuration) -### Compose File for Custom-Built Images +### Compose File for custom-built images This guide uses [`docker-compose.yml`](../docker-compose.yml), which is specifically designed for **custom-built images** based on `hackolade/studio`. This compose file: - Uses traditional data paths (`/home/hackolade/Documents/*`) @@ -38,7 +38,7 @@ This guide uses [`docker-compose.yml`](../docker-compose.yml), which is specific **Note:** If you want to use the pre-built `hackolade/hck-cli` image instead, use [`compose.yml`](../compose.yml) which is designed for the pre-built image. See [getting-started-hck-cli.md](./getting-started-hck-cli.md) for details. -## Building Your Own vs. Pre-built Image +## Building your own vs. pre-built image Before you start, decide which approach fits your needs: @@ -49,7 +49,7 @@ Before you start, decide which approach fits your needs: | Entrypoint | `startup.sh` script | `hck-cli` binary | | Updates | Rebuild image | Pull new version | | Plugins | Select during build | All included | -| Architecture support | Depends on build platform | Multi-arch (AMD64 + ARM64) | +| Architecture support | AMD64/x86_64 only (Intel-based chips) | Multi-arch (AMD64 + ARM64) | | Customization | Full control | Limited | **When to use the pre-built image:** @@ -68,7 +68,7 @@ Before you start, decide which approach fits your needs: **🔨 Need to build your own?** Continue with this guide to learn how to build a custom image with selected plugins. -## ⚠️ Migration Notice for Existing Users +## ⚠️ Migration notice for existing users If you are currently using a custom-built image based on `hackolade/studio` and have an existing `docker-compose.yml` file, **you must migrate to the new `compose.yml` structure** when using the pre-built `hackolade/hck-cli` image. @@ -96,17 +96,17 @@ Before you begin, make sure you have: -## Step 1: Understanding Data Storage +## Step 1: Understanding data storage Hackolade needs to store and access data. We use **volumes** to make data persist between container runs. -### Required Storage Locations +### Required storage locations Inside the container, Hackolade uses these folders: -- `/home/hackolade/.config/Hackolade` - Application data (settings, license info) -- `/home/hackolade/Documents/HackoladeLogs` - Log files -- `/home/hackolade/Documents/output` - Generated files (documentation, schemas, etc.) -- `/home/hackolade/Documents/models` - Your model files (input) +- `/home/hackolade/.config/Hackolade` : Application data (settings, license info) +- `/home/hackolade/Documents/HackoladeLogs` : Log files +- `/home/hackolade/Documents/output` : Generated files (documentation, schemas, etc.) +- `/home/hackolade/Documents/models` : Your model files (input) **Important notes on folder customization:** @@ -116,7 +116,7 @@ Inside the container, Hackolade uses these folders: - **Application data (`/home/hackolade/.config/Hackolade`)**: **Cannot be moved** and bind mounting it can create unexpected issues. It's safer to keep it in a Docker named volume (which is the default in our examples). -### Setting Up Storage: Docker CLI Method +### Setting up storage: Docker CLI method With Docker CLI, you'll create **named volumes** (Docker-managed storage) and **bind mounts** (folders on your computer). @@ -135,7 +135,7 @@ chown -R 1000:0 ./models **Why `chown 1000:0`?** The container runs as user `hackolade` with UID 1000 and GID 0. This command ensures the folder is writable by the container. -### Setting Up Storage: Docker Compose Method +### Setting up storage: Docker Compose method Docker Compose automatically creates volumes when you first run it. You just need to create the models folder: @@ -149,11 +149,11 @@ The [`docker-compose.yml`](../docker-compose.yml) file (already in this reposito -## Step 2: Building the Docker Image +## Step 2: Building the Docker image First, you need to build a Docker image that contains Hackolade Studio. -### Docker CLI Method +### Docker CLI method ```bash docker build --no-cache --pull -t hackolade:latest . @@ -166,7 +166,7 @@ docker build --no-cache --pull -t hackolade:latest . - `-t hackolade:latest` - Tags the image with name "hackolade" and version "latest" - `.` - Uses the Dockerfile in the current directory -### Docker Compose Method +### Docker Compose method Docker Compose doesn't build images directly, but you can still use the same Docker CLI command: @@ -178,11 +178,11 @@ docker build --no-cache --pull -t hackolade:latest . -## Step 3: Validating Your License +## Step 3: Validating your license Before you can use Hackolade CLI, you must validate your license key for the Docker image. -### Docker CLI Method +### Docker CLI method **Step 3a: Get the computer ID** ```bash @@ -216,7 +216,7 @@ Replace: For offline validation, see the detailed instructions in [license-validation.md](./license-validation.md). -### Docker Compose Method +### Docker Compose method **Step 3a: Get the computer ID** ```bash @@ -236,11 +236,11 @@ This single command does both steps automatically by using `$(...)` to get the U -## Step 4: Running Hackolade CLI Commands +## Step 4: Running Hackolade CLI commands Now you're ready to run Hackolade CLI commands! -### Docker CLI Method +### Docker CLI method **Basic command structure:** ```bash @@ -254,14 +254,14 @@ docker run --rm \ ``` **What each part does:** -- `docker run --rm` - Run container and remove when done -- `-v hackolade-studio-app-data:...` - Mount app data volume -- `-v hackolade-studio-logs:...` - Mount logs volume -- `-v hackolade-studio-output:...` - Mount output volume -- `-v ${PWD}/models:...` - Mount your local models folder -- `-w /home/hackolade/Documents` - Set working directory -- `hackolade:latest` - The image to use -- `COMMAND [OPTIONS]` - The Hackolade CLI command +- `docker run --rm` : Run container and remove when done +- `-v hackolade-studio-app-data:...` : Mount app data volume +- `-v hackolade-studio-logs:...` : Mount logs volume +- `-v hackolade-studio-output:...` : Mount output volume +- `-v ${PWD}/models:...` : Mount your local models folder +- `-w /home/hackolade/Documents` : Set working directory +- `hackolade:latest` : The image to use +- `COMMAND [OPTIONS]` : The Hackolade CLI command **Example: Show help** ```bash @@ -306,9 +306,9 @@ docker compose run --rm hackoladeStudioCLI version -## Step 5: Common Scenarios +## Step 5: Common scenarios -### Scenario 1: Generate Documentation +### Scenario 1: Generate documentation Generate HTML documentation from a model file. @@ -334,7 +334,7 @@ docker compose run --rm hackoladeStudioCLI genDoc \ --doc=/home/hackolade/Documents/output/doc.html ``` -### Scenario 2: Forward Engineering +### Scenario 2: Forward engineering Generate JSON Schema files from a model. @@ -366,7 +366,7 @@ docker compose run --rm hackoladeStudioCLI forweng \ --outputtype=jsonschema ``` -### Scenario 3: Reverse Engineering +### Scenario 3: Reverse engineering Reverse engineer a database to create a model. @@ -396,7 +396,7 @@ docker compose run --rm hackoladeStudioCLI revEng \ --inferRelationships=true ``` -### Scenario 4: Compare Two Models +### Scenario 4: Compare two models Compare two model files and generate a delta model. @@ -424,11 +424,11 @@ docker compose run --rm hackoladeStudioCLI compMod \ -## Step 6: Retrieving Generated Files +## Step 6: Retrieving generated files After running commands, you need to copy files from Docker volumes to your computer. -### Docker CLI Method +### Docker CLI method **Retrieve output files:** ```bash @@ -458,7 +458,7 @@ docker run --rm --init \ - Uses `cp` command to copy files from volume to local folder - Removes container when done (`--rm`) -### Docker Compose Method +### Docker Compose method Docker Compose doesn't have a built-in way to extract files, so you still use Docker CLI: @@ -484,7 +484,7 @@ docker run --rm --init \ -## Creating a Helper Script (Optional) +## Creating a helper script (optional) To make Docker CLI commands easier, you can create a helper script. @@ -515,7 +515,7 @@ chmod +x run-hackolade.sh ## Troubleshooting -### Permission Denied Errors +### Permission denied Errors **Note:** This only applies to **bind mounts** (folders on your host computer), not to Docker named volumes. @@ -554,9 +554,9 @@ docker volume create hackolade-studio-output -## Quick Reference +## Quick reference -### Docker CLI Quick Commands +### Docker CLI quick commands ```bash # Build image @@ -577,7 +577,7 @@ docker run --rm \ hackolade:latest COMMAND ``` -### Docker Compose Quick Commands +### Docker Compose quick commands ```bash # Build image (same as Docker CLI)