“

Series: S12 Developer Tutorials · Article 1 | Level: Beginner | Reading Time: 15 min

Deploy coomia-dip Locally in 5 Minutes

#Introduction

In the wave of enterprise digital transformation, the importance of data platforms cannot be overstated. Palantir Foundry stands as an industry benchmark with its powerful ontology modeling and data fusion capabilities, but its prohibitive licensing costs put it beyond reach for many organizations. Enter coomia-dip — an open-source, ontology-driven intelligent decision Platform-as-a-Service (PaaS) built to rival Palantir Foundry.

This tutorial will guide you through deploying coomia-dip locally in under 5 minutes, giving you rapid access to the platform's core capabilities. Whether you are an architect evaluating technical solutions or a developer looking to get started quickly, this tutorial provides the most streamlined onboarding path.

#Prerequisites

Before you begin, ensure your development machine meets the following requirements:

#Hardware Requirements

CPU: 4+ cores (8 cores recommended)
Memory: 16 GB minimum (32 GB recommended)
Disk: At least 20 GB free space (SSD recommended)

#Software Requirements

OS: Linux (Ubuntu 20.04+), macOS 12+, Windows 10/11 (WSL2 required)
Docker: 24.0+ with Docker Compose v2 integrated
Git: 2.30+
Python: 3.11+ (for SDK interaction)
Java: JDK 21+ (for Control Layer development, optional for deployment)

#Verify Your Environment

Open a terminal and run the following commands to verify your setup:

Bash

# Verify Docker
docker --version
# Expected: Docker version 24.x.x or higher

# Verify Docker Compose
docker compose version
# Expected: Docker Compose version v2.x.x

# Verify Git
git --version
# Expected: git version 2.30+

# Verify Python
python3 --version
# Expected: Python 3.11+

# Verify Java (optional)
java --version
# Expected: openjdk 21+

If any tool is missing, refer to the respective official documentation for installation. Docker Desktop users on Windows and macOS typically have Docker Compose included.

#Step 1: Clone the Repository

Bash

# Clone the coomia-dip repository
git clone https://github.com/coomia-dip/coomia-dip.git
cd coomia-dip

# Explore the project structure
ls -la

You will see the following core directory structure:

Code

coomia-dip/
├── control-Layer/          # Control Layer: Control Layer (Spring Boot 3.x, Java 21)
├── data-Layer/             # Data Layer: Data Layer (Quarkus 3.x, Iceberg)
├── intelligence-Layer/     # Reasoning & Decision Layer + Agent Runtime Layer: Reasoning & Decision + Agent Runtime
├── deployment-Layer/       # Deployment & Operations Layer: Deployment & Operations
├── sdk-Layer/              # SDK & Developer Experience Layer: SDK and Developer Experience
├── python-sdk/             # Python SDK
├── docker-compose.yml      # One-click deployment orchestration
├── docs/                   # Design documentation
├── tests/                  # Test code
└── sprints/                # Sprint management

#Layered Architecture Overview

coomia-dip adopts an 8-Layer layered architecture where each Layer handles independent concerns:

Layer	Name	Responsibility	Tech Stack
A	Platform Deployment & Ops	Deployment orchestration & operations	Docker Compose, Python
B	Control Layer	Ontology management, metadata, permissions	Spring Boot 3.x, Java 21, gRPC
C	Data Layer	Data storage, Pipelines, computation	Quarkus 3.x, Iceberg+Nessie
D	Reasoning & Decision	Reasoning engine, rule engine	Python 3.x, FastAPI, gRPC
E	Agent Runtime	AI Agent execution environment	Python 3.x, FastAPI, Temporal
F	Pipeline & Orchestration	Data pipeline orchestration	Merged into Data Layer
G	Metadata & Governance	Metadata governance	Merged into Control Layer
H	SDK & Developer Experience	SDK, CLI, code generation	Python SDK, TypeScript

#Step 2: Configure Environment Variables

coomia-dip provides default development environment configuration. You just need to copy the template file:

Bash

# Copy the environment variable template
cp .env.example .env

# Review the default configuration
cat .env

The default .env file contains these key configurations:

ENV

# Platform base configuration
coomia-dip_ENV=development
coomia-dip_VERSION=latest

# Database configuration (PostgreSQL)
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=coomia-dip
POSTGRES_USER=onto_admin
POSTGRES_PASSWORD=onto_dev_2024

# Doris configuration (OLAP engine)
DORIS_FE_HOST=doris-fe
DORIS_FE_HTTP_PORT=8030
DORIS_FE_QUERY_PORT=9030

# Kafka configuration
KAFKA_BOOTSTRAP_SERVERS=kafka:9092

# Nessie configuration (Data version management)
NESSIE_URI=http://nessie:19120/api/v1

# Temporal configuration (Workflow engine)
TEMPORAL_HOST=temporal
TEMPORAL_PORT=7233

# gRPC port configuration
CONTROL_PLANE_GRPC_PORT=50051
DATA_PLANE_GRPC_PORT=50052
INTELLIGENCE_PLANE_GRPC_PORT=50053

For local development, the default configuration usually requires no modification. If you have local port conflicts, adjust the corresponding port numbers.

#Custom Configuration (Optional)

If you need to connect to existing external databases or message queues, modify the corresponding settings in the .env file:

Bash

# Example: Using an existing PostgreSQL
POSTGRES_HOST=your-postgres-host
POSTGRES_PORT=5432
POSTGRES_DB=your_database
POSTGRES_USER=your_user
POSTGRES_PASSWORD=your_password

#Step 3: One-Click Launch

This is the most exciting step — one command to start the entire platform:

Bash

# Start all services using Docker Compose
docker compose up -d

# Monitor startup progress
docker compose ps

#Startup Process Explained

Docker Compose will start the following services in dependency order:

Infrastructure Layer (~30 seconds)
- PostgreSQL: Relational data storage
- Doris FE/BE: OLAP analytics engine
- Kafka + ZooKeeper: Message queue
- MinIO: Object storage (S3 compatible)
- Nessie: Data version management
Platform Service Layer (~60 seconds)
- Control Layer (gRPC :50051): Ontology management service
- Data Layer (gRPC :50052): Data service
- Intelligence Layer (gRPC :50053): Reasoning service
Runtime Layer (~30 seconds)
- Temporal Server: Workflow engine
- Temporal Worker: Workflow executor

#Wait for Services to Be Ready

Bash

# Wait for all health checks to pass (~2-3 minutes)
docker compose ps --format "table {{.Name}}\t{{.Status}}"

Expected output should show all services as Up or Up (healthy):

Code

NAME                    STATUS
coomia-dip-postgres      Up (healthy)
coomia-dip-doris-fe      Up (healthy)
coomia-dip-doris-be      Up (healthy)
coomia-dip-kafka         Up (healthy)
coomia-dip-nessie        Up (healthy)
coomia-dip-minio         Up (healthy)
coomia-dip-control       Up (healthy)
coomia-dip-data          Up (healthy)
coomia-dip-intelligence  Up (healthy)
coomia-dip-temporal      Up (healthy)

#Common Startup Troubleshooting

Issue 1: Port Conflicts

Bash

# Check port usage
lsof -i :5432   # PostgreSQL
lsof -i :9092   # Kafka
lsof -i :50051  # Control Layer gRPC

# Solution: Modify the corresponding port in .env

Issue 2: Insufficient Memory

Bash

# Check Docker available memory
docker info | grep "Total Memory"

# If memory is below 8 GB, start in minimal mode
docker compose -f docker-compose.minimal.yml up -d

Issue 3: Image Pull Timeout

Bash

# Configure Docker registry mirrors if needed
# Add to /etc/docker/daemon.json
{
  "registry-mirrors": ["https://mirror.example.com"]
}

# Restart Docker
sudo systemctl restart docker

#Step 4: Verify the Deployment

#4.1 Health Check

Bash

# Check Control Layer health
curl http://localhost:8080/actuator/health

# Expected response
{
  "status": "UP",
  "components": {
    "db": {"status": "UP"},
    "grpc": {"status": "UP"},
    "kafka": {"status": "UP"}
  }
}

#4.2 Connect Using the Python SDK

Install the coomia-dip Python SDK:

Bash

# Install SDK
pip install ontology-sdk

# Or install from local source
cd python-sdk
pip install -e .

Write a quick verification script:

Python

from ontology_sdk import OntoPlatform

# Connect to local coomia-dip instance
platform = OntoPlatform(
    control_plane_url="localhost:50051",
    data_plane_url="localhost:50052",
    intelligence_plane_url="localhost:50053"
)

# Verify connection
status = platform.health_check()
print(f"Platform status: {status}")
# Output: Platform status: HealthStatus(control=UP, data=UP, intelligence=UP)

# List existing ObjectTypes
object_types = platform.ontology.list_object_types()
print(f"Registered ObjectType count: {len(object_types)}")

#4.3 Direct gRPC Connection

If you prefer direct gRPC interaction, you can use grpcurl for testing:

Bash

# Install grpcurl
brew install grpcurl  # macOS
# Or: go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

# List available gRPC services
grpcurl -plaintext localhost:50051 list

# Call health check
grpcurl -plaintext localhost:50051 grpc.health.v1.Health/Check

# List ObjectTypes
grpcurl -plaintext localhost:50051 onto.control.OntologyService/ListObjectTypes

#4.4 Access Management Interfaces

coomia-dip provides several management interfaces:

Interface	URL	Purpose
Platform Console	http://localhost:3000↗	Platform management dashboard
Doris FE	http://localhost:8030↗	OLAP query interface
MinIO Console	http://localhost:9001↗	Object storage management
Temporal UI	http://localhost:8233↗	Workflow monitoring
Kafka UI	http://localhost:8082↗	Message queue monitoring

#Step 5: Run the Example Project

coomia-dip includes a built-in "Project Management" example to help you quickly understand core concepts:

Python

from ontology_sdk import OntoPlatform

platform = OntoPlatform(
    control_plane_url="localhost:50051",
    data_plane_url="localhost:50052"
)

# 1. Create an ObjectType (ontology type definition)
project_type = platform.ontology.create_object_type(
    name="Project",
    display_name="Project",
    properties={
        "name": {"type": "string", "required": True},
        "status": {"type": "enum", "values": ["planning", "active", "completed"]},
        "budget": {"type": "decimal"},
        "start_date": {"type": "date"},
        "end_date": {"type": "date"}
    }
)
print(f"Created ObjectType: {project_type.name} (rid={project_type.rid})")

# 2. Create a project instance
project = platform.objects.create(
    object_type="Project",
    properties={
        "name": "coomia-dip v1.0",
        "status": "active",
        "budget": 500000,
        "start_date": "2024-01-01",
        "end_date": "2024-12-31"
    }
)
print(f"Created project: {project.properties['name']} (rid={project.rid})")

# 3. Query projects
results = platform.objects.search(
    object_type="Project",
    filter={"status": {"eq": "active"}}
)
for obj in results:
    print(f"  - {obj.properties['name']}: {obj.properties['status']}")

After running this script, you should see:

Code

Created ObjectType: Project (rid=ri.ontology.object-type.project-xxx)
Created project: coomia-dip v1.0 (rid=ri.ontology.object.project-yyy)
  - coomia-dip v1.0: active

#Deployment Architecture Diagram

The local deployment architecture is as follows:

Code

┌─────────────────────────────────────────────────────────┐
│                    Developer Machine                      │
│                                                           │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────┐  │
│  │ Python SDK  │  │  gRPC Client │  │  Web Console    │  │
│  │ (pip)       │  │  (grpcurl)   │  │  (localhost:3000)│  │
│  └──────┬──────┘  └──────┬───────┘  └────────┬────────┘  │
│         │                │                    │           │
│  ═══════╪════════════════╪════════════════════╪═══════    │
│         │         Docker Network              │           │
│  ┌──────▼──────┐  ┌──────▼───────┐  ┌────────▼────────┐  │
│  │Control Layer│  │  Data Layer  │  │Intelligence     │  │
│  │ :50051 gRPC │  │ :50052 gRPC  │  │Layer :50053 gRPC│  │
│  └──────┬──────┘  └──────┬───────┘  └────────┬────────┘  │
│         │                │                    │           │
│  ┌──────▼────────────────▼────────────────────▼────────┐  │
│  │              Infrastructure Layer                    │  │
│  │  PostgreSQL │ Doris │ Kafka │ MinIO │ Nessie │Tempo  │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

#Resource Management and Cleanup

#Stop Services

Bash

# Stop all services (preserve data volumes)
docker compose stop

# Restart services
docker compose start

#Full Cleanup

Bash

# Stop and remove all containers and networks
docker compose down

# Also remove data volumes (use with caution!)
docker compose down -v

#View Resource Usage

Bash

# View container resource usage
docker stats --no-stream

# View disk usage
docker system df

#Next Steps

Congratulations! You have successfully deployed coomia-dip locally. Next, you can:

Your First Ontology — Deep dive into creating ObjectType and RelationType
Your First Data — Learn entity CRUD operations
Your First Action — Define and execute business operations
OQL Query Guide — Master the powerful Ontology Query Language

#Frequently Asked Questions

#Q: What is the difference between coomia-dip and Palantir Foundry?

coomia-dip is an open-source alternative to Palantir Foundry. It implements Foundry's core concepts — ontology-driven modeling, data fusion, reasoning and decision-making — but uses an entirely open-source technology stack. Key differences include:

Licensing: coomia-dip is fully open-source (Apache 2.0); Foundry is commercially licensed
Deployment: coomia-dip supports private deployment and self-hosting; Foundry is primarily offered as SaaS
Tech Stack: coomia-dip uses Spring Boot + Quarkus + FastAPI + gRPC; Foundry uses a proprietary stack
Extensibility: coomia-dip offers more open plugin and custom function mechanisms

#Q: What are the minimum resource requirements?

Minimal deployment (using docker-compose.minimal.yml) requires:

4 CPU cores
8 GB memory
10 GB disk space

Minimal mode disables Doris (uses PostgreSQL for OLAP queries instead) and Temporal, suitable for quickly experiencing core features.

#Q: Does it support Kubernetes deployment?

Yes, coomia-dip provides Helm Charts for Kubernetes deployment. See the Production Deployment Checklist for details.

#Q: How do I upgrade versions?

Bash

# Pull latest code
git pull origin main

# Pull latest images
docker compose pull

# Restart (automatically runs database migrations)
docker compose up -d

#Q: Where is data persisted?

All data is stored in Docker named volumes:

coomia-dip-postgres-data: PostgreSQL data
coomia-dip-doris-data: Doris data
coomia-dip-kafka-data: Kafka messages
coomia-dip-minio-data: MinIO object storage
coomia-dip-nessie-data: Nessie version data

#Summary

In this tutorial, we completed the following steps:

Environment Preparation: Verified Docker, Git, Python, and other tool versions
Repository Cloning: Obtained the coomia-dip source code and explored the project structure
Environment Configuration: Copied and reviewed environment variable settings
One-Click Deployment: Started all services using docker compose up -d
Deployment Verification: Confirmed the platform is running through health checks, SDK connection, and the example project

The entire process takes under 5 minutes (excluding image download time), and you now have a fully functional ontology-driven intelligent decision platform. In the following tutorials, we will dive deep into each of coomia-dip's core capabilities.

This article is the first in the coomia-dip Developer Tutorial series. coomia-dip is an open-source alternative to Palantir Foundry, committed to making world-class data intelligence platforms accessible to every organization.

Repository: https://github.com/coomia-dip/coomia-dip↗ License: Apache License 2.0