Catalogs and Repositories
Overview
OctoMesh distinguishes between Catalogs and Repositories for managing Construction Kit Model Libraries:
- Catalog: A file-based storage system that provides various Construction Kit Model Libraries in multiple versions. Catalogs serve as the source from which libraries can be imported.
- Repository: A database-stored (e.g., MongoDB) collection of Construction Kit Model Libraries that work together. A repository contains exactly one version of each library, and all libraries must be logically compatible with each other.
Catalogs
Catalogs are file-based storage systems that centrally provide Construction Kit Model Libraries for OctoMesh. They can contain multiple versions of the same library, allowing you to choose which version to import into a repository.
Catalog Types
File System Catalog
Local directory structure containing Construction Kit library definitions. Suitable for development environments or on-premise deployments.
Default paths:
- Windows:
%USERPROFILE%\.octo-ck-models - macOS:
~/octo-ck-models - Linux:
~/.octo-ck-models
Git Catalog
GitHub or other Git-based sources for version-controlled, distributed access to Construction Kit libraries. Enables collaboration and change tracking across teams.
By default, the meshmakers Git catalog is configured, available at meshmakers.github.io.
System Libraries
Core Construction Kit libraries are compiled directly into OctoMesh services' source code. These system libraries are automatically available without external catalog configuration and provide fundamental data types and patterns required by the platform.
Catalog Structure
Construction Kit libraries are stored in validated form within catalogs. The validated form contains all types, attributes, records, enums, and associations. Catalogs can hold multiple versions of the same library (e.g., Industry.Energy-1.0.0, Industry.Energy-1.1.0, Industry.Energy-2.0.0).
Dependency Resolution
Catalogs are searched to resolve dependencies when importing libraries. The search order is:
- Embedded System Construction Kits - Built-in libraries compiled into OctoMesh services
- Local File System Catalog - User-specific or project-specific libraries
- GitHub Catalog - Shared libraries from the configured Git source
Managing Catalogs with octo-ckc
The octo-ckc tool provides commands for working with catalogs:
List Available Catalogs
octo-ckc -c GetCatalogs
Lists all known Construction Kit catalogs with their names and descriptions.
Publish to Catalog
octo-ckc -c Publish -f <file> [-c <catalog>] [-r]
| Parameter | Description |
|---|---|
-f, --file | Path of the compiled construction kit model file (required) |
-c, --catalog | Name of the catalog (default: LocalFileSystemCatalog) |
-r, --replace | Replace existing model if it already exists |
Get Model from Catalog
octo-ckc -c Get -c <catalog> -n <name> [-f <file>]
| Parameter | Description |
|---|---|
-c, --catalog | Name of the catalog (required) |
-n, --name | Name of the construction kit model to retrieve (required) |
-f, --file | Optional output file path to store the model |
Find Model in Catalogs
octo-ckc -c Find -id <modelId>
| Parameter | Description |
|---|---|
-id, --modelId | Model ID to find, including version ranges (required) |
Searches all known catalogs for the specified model.
Restore Dependencies
octo-ckc -c Restore -f <file> -o <outputPath> [-c <cache>]
| Parameter | Description |
|---|---|
-f, --file | Path of the model configuration file (required) |
-o, --outputPath | Output path for compiled construction kits (required) |
-c, --cache | Optional cache file path for dependent models |
Restores all construction kit dependencies based on a model configuration file.
Refresh Catalog Cache
octo-ckc -c RefreshCatalogCache [-c <catalog>]
| Parameter | Description |
|---|---|
-c, --catalog | Name of the catalog (default: LocalFileSystemCatalog) |
Refreshes the cache for a specific catalog by reloading from disk or fetching from remote sources.
octo-ckc -c RefreshAllCatalogCaches
Refreshes the cache for all known catalogs.
Repositories
A Repository is a coherent set of Construction Kit Model Libraries stored in a database (such as MongoDB). Unlike catalogs, repositories enforce strict version compatibility:
- Single Version Rule: A repository contains exactly one version of each Model Library
- Version Compatibility: All libraries in a repository must be logically compatible with each other
- Dependency Consistency: Library dependencies must be satisfied within the same repository
Repository Characteristics
| Aspect | Description |
|---|---|
| Storage | Database (e.g., MongoDB) |
| Versions per Library | Exactly one |
| Compatibility | All libraries must work together |
| Purpose | Runtime data model for OctoMesh instances |
Importing Libraries
When importing a Construction Kit Model Library from a catalog into a repository:
- The system checks if the library's dependencies are satisfied
- Version compatibility with existing libraries is verified
- If a different version of the library already exists, it must be upgraded or the import fails
- All dependent libraries must have compatible versions
Example
A repository might contain:
Repository "production"
├── System-1.0.3
├── Basic-1.0.0 (depends on System-1.0.3)
├── Industry.Energy-1.0.0 (depends on Basic-1.0.0)
└── EnergyCommunity-1.0.0 (depends on Industry.Energy-1.0.0, Basic-1.0.0)
All libraries form a coherent set where dependencies are satisfied and versions are compatible.
Comparison
| Aspect | Catalog | Repository |
|---|---|---|
| Storage | File system or GitHub | Database (e.g., MongoDB) |
| Multiple versions | Yes | No (one per library) |
| Purpose | Library distribution | Runtime data model |
| Version constraints | None | Strict compatibility |
| Dependencies | Can be unresolved | Must be fully resolved |