← Back to Home

sdc4

SDC4 Data Model Container Project

Generated by SDCStudio AppGen (Enterprise Stack) on 2026-03-08

Enterprise Stack Overview

This application uses the Enterprise Stack which includes:

Service Purpose Port Username Password
Django Web application 18000 admin admin123
PostgreSQL Operational database 15432 admin admin123
GraphDB OWL 2 reasoning triplestore 17200 admin admin123
SirixDB Temporal JSON/XML database 19443 admin admin123
Keycloak SSO/RBAC authentication 18080 admin admin123
Redis Celery message broker 16379 - -

All services use the same default credentials: admin / admin123

Change these in production! See .env.example for configuration.

Memory Requirement: 6GB+ free RAM recommended

The Enterprise Stack runs multiple services (GraphDB, SirixDB, Keycloak, PostgreSQL, Redis). Ensure Docker/Podman has at least 6GB of memory allocated for stable operation.

Key Benefits

Prerequisites

You need either Docker or Podman installed:

Note: Docker Desktop requires a license for organizations with >250 employees or >$10M revenue.

Option 2: Podman (Free Alternative)

Quick Start

1. Copy environment file

cp .env.example .env

2. Start the application

Using Docker:

docker compose up -d --build

Using Podman:

podman-compose up -d --build

The -d flag runs services in the background. The --build flag ensures images are rebuilt with any changes.

Note: First startup may take 2-3 minutes as GraphDB and Keycloak initialize.

To view logs if needed:

docker compose logs -f    # or: podman-compose logs -f

3. Access the application

Default Credentials (all services): - Username: admin - Password: admin123

Service URLs: - Django Admin: http://localhost:18000/admin/ - GraphDB Workbench: http://localhost:17200 (repository: sdc4_rdf) - Keycloak Admin: http://localhost:18080/admin/ (realm: sdc4) - SirixDB API: https://localhost:19443 (uses self-signed certificate) - PostgreSQL: localhost:15432 (database: sdc4_db)

Application URLs: - Home Page: http://localhost:18000 (Table of Contents for all apps) - Admin Interface: http://localhost:18000/admin/ - SSO Login: http://localhost:18000/accounts/keycloak/login/

Automatic Initialization:

On first startup, the application automatically: 1. Creates PostgreSQL database and tables 2. Creates Django superuser (admin/admin123) 3. Creates GraphDB repository with OWL 2 RL reasoning (sdc4_rdf) 4. Loads SDC4 ontologies (sdc4.ttl, sdc4-meta.ttl) into GraphDB 5. Initializes Keycloak realm (if realm import is configured) 6. Collects static files

IMPORTANT: Change these passwords in production! See "Production Deployment" section below.

4. Optional: Create additional users

To create more admin users:

Via Django Admin:

docker compose exec web python manage.py createsuperuser

Via Keycloak Admin Console: 1. Go to http://localhost:18080/admin/ 2. Login with admin/admin123 3. Navigate to Users > Add user

Customizing Your Application

This application was generated with a semantic foundation (RDF, SHACL, XSD) and basic CRUD interfaces. You can now customize it to match your specific needs and design preferences.

Using AI Coding Assistants

The generated code is clean, well-structured Django that works great with AI coding assistants like Claude Code, GitHub Copilot, or Cursor:

# In your deployed app directory
claude-code  # or: cursor, copilot, etc.

Example customization prompts: - "Add Tailwind CSS and modernize the UI with a dark mode option" - "Create a dashboard with charts and analytics for this data" - "Add a REST API with JWT authentication" - "Integrate with Stripe for payment processing" - "Add real-time updates with WebSockets" - "Create custom reports with PDF export" - "Add email notifications when new records are created" - "Integrate with our existing SSO authentication system"

What's Already Built For You

✅ SDC4-compliant semantic models - Full RDF/OWL ontology integration ✅ RDF/SHACL/XSD schemas - Standards-based validation and interoperability ✅ Knowledge graph integration - GraphDB with OWL 2 RL reasoning ✅ Enterprise SSO - Keycloak authentication with SAML/OAuth2 ✅ Temporal database - SirixDB for time-travel queries ✅ Data validation - Automatic constraint checking and error messages ✅ Database migrations - Django ORM with PostgreSQL backend ✅ Basic CRUD interfaces - Create, read, update, delete functionality ✅ Bulk import/export - CSV/JSON data operations ✅ Docker deployment - Production-ready containerization

What You Can Customize

🎨 UI/UX Styling - Replace Bootstrap with Tailwind, add custom themes, improve layouts 🔌 Third-party Integrations - Connect to APIs, payment processors, analytics platforms 📊 Custom Dashboards - Create charts, reports, and data visualizations 🔐 Authentication/Authorization - Extend Keycloak, add custom permissions 📧 Notifications & Workflows - Email alerts, Slack integration, automated tasks 🚀 Performance Optimizations - Caching, query optimization, CDN integration 📱 Mobile Support - Progressive web app, native mobile apps 🌐 Localization - Multi-language support, timezone handling

Why This Two-Stage Approach Works

Stage 1 (SDCStudio) solves the hard problems AI struggles with: - Complex semantic modeling decisions - Standards compliance (SDC4, RDF, SHACL, XSD) - Knowledge graph architecture with reasoning - Enterprise SSO configuration - Multi-format consistency - Data validation rules

Stage 2 (AI Assistants) excels at what you need next: - Visual design and user experience - Custom business logic - Integration with your existing systems - Workflow automation - Feature additions

The plain UI is intentional - it's a semantic foundation ready for your customizations, not a limitation!

Port Customization

If default ports conflict with existing services, customize in .env:

DB_PORT=15433           # Default: 15432
GRAPHDB_PORT=17201      # Default: 17200
SIRIX_PORT=19444        # Default: 19443
KEYCLOAK_PORT=18081     # Default: 18080
REDIS_PORT=16380        # Default: 16379
WEB_PORT=18001          # Default: 18000

Enterprise Services

GraphDB (OWL 2 Reasoning)

GraphDB provides semantic reasoning capabilities:

Features: - OWL 2 RL reasoning rules - SHACL validation support - RDF4J-compatible API - Visual SPARQL query builder

SirixDB (Temporal Versioning)

SirixDB provides temporal data storage:

Features: - Time-travel queries - Efficient diff computation - JSON and XML document storage - Revision history

Note: SirixDB uses self-signed certificates. Configure SIRIX_VERIFY_SSL=false for development.

Keycloak (SSO/RBAC)

Keycloak provides enterprise authentication:

Supported Protocols: - OAuth 2.0 - OpenID Connect (OIDC) - SAML 2.0

Features: - Single Sign-On (SSO) - Role-Based Access Control (RBAC) - Identity Provider federation - User self-registration

REST API

This application includes a REST API for external integrations. The API allows external systems to: - Upload generated app ZIP files - Upload schema files (XSD, HTML, OWL) - Upload RDF/Turtle files to the triplestore - Validate and store XML instances

API Authentication

The API uses API Key authentication via the X-API-Key header.

Creating API Keys

Via Django Admin (Recommended):

  1. Access Django Admin: http://localhost:18000/admin/
  2. Navigate to API → API Keys
  3. Click Add API Key
  4. Enter:
  5. Organization Name: Name of the organization or system that will use this key
  6. Contact Email: Contact email for the key holder
  7. Click Save
  8. ⚠️ COPY THE DISPLAYED KEY IMMEDIATELY - it cannot be retrieved later!

The generated key will look like: sdc4_xK9mN2pQ7rS4tU6vW8xY0zA3bC5dE7fG...

Security Notes: - API keys are stored as SHA-256 hashes (plaintext never stored) - Keys are shown only once at creation time - Keys can be deactivated without deletion (preserves audit trail) - Usage is tracked (last_used_at, request_count)

Sharing API Keys

When sharing API keys with external systems:

  1. Secure Transmission: Send keys via secure channels (encrypted email, password manager, secure vault)
  2. Documentation: Provide the API endpoint URLs and authentication instructions
  3. Testing: Test the key with a simple request before sharing
  4. Monitoring: Monitor usage via Django Admin (request count, last used date)
  5. Rotation: Deactivate and recreate keys periodically for security

Example sharing instructions for external systems:

API Base URL: http://your-domain.com/api/v1/

Authentication: Add header to all requests:
  X-API-Key: sdc4_your_api_key_here

Available Endpoints:
- POST /api/v1/upload/zip/      # Upload app ZIP files
- POST /api/v1/upload/schema/   # Upload schema files
- POST /api/v1/upload/rdf/      # Upload RDF/Turtle files
- POST /api/v1/validate/xml/    # Validate XML instances

See full API documentation: api/README.md

API Endpoints

Base URL: http://localhost:18000/api/v1/ (change in production)

All endpoints require the X-API-Key header:

curl -H "X-API-Key: your-api-key" http://localhost:18000/api/v1/...

Upload ZIP App

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -F "file=@app.zip" \
  http://localhost:18000/api/v1/upload/zip/

Upload Schema Files

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -F "files=@dm-abc123.xsd" \
  -F "files=@dm-abc123.html" \
  http://localhost:18000/api/v1/upload/schema/

Upload RDF/Turtle

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -F "file=@dm-abc123.ttl" \
  http://localhost:18000/api/v1/upload/rdf/

Validate XML Instance

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -F "file=@instance.xml" \
  http://localhost:18000/api/v1/validate/xml/

API Documentation

Complete API documentation with detailed examples is available at: - Local: api/README.md in this project - Online: (Configure your documentation URL)

Managing API Keys

View All Keys (Django Admin): - Navigate to API → API Keys - See: organization name, key prefix, status, usage stats

Deactivate a Key: 1. Click on the key in Django Admin 2. Uncheck "Is active" 3. Click Save

Note: Deactivated keys are retained for audit purposes. The plaintext key cannot be recovered.

Usage Monitoring: - Request Count: Total API calls made with this key - Last Used: Timestamp of most recent API call - Check these regularly to detect unusual activity

Development

Run migrations

docker compose exec web python manage.py migrate

Collect static files

docker compose exec web python manage.py collectstatic

Django shell

docker compose exec web python manage.py shell

Re-initialize GraphDB

If you need to reload ontologies:

docker compose exec web python manage.py init_graphdb

Stopping the Application

docker compose down

Note: This stops containers but preserves all data in mediafiles/ directories.

Backup and Restore

All application data is stored in the mediafiles/ directory:

Backup

tar -czf sdc4_backup_$(date +%Y%m%d).tar.gz sdc4/

Restore

  1. Extract backup to desired location
  2. Navigate to project directory
  3. Start the application: bash docker compose up -d --build

Production Deployment

  1. Generate a secure SECRET_KEY: bash python -c 'from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())'
  2. Set DEBUG=False in .env
  3. Configure ALLOWED_HOSTS with your domain
  4. Use strong passwords for all services
  5. Configure KEYCLOAK_CLIENT_SECRET properly
  6. Enable SSL verification for SirixDB: SIRIX_VERIFY_SSL=true
  7. Set up HTTPS/SSL (use nginx or Caddy as reverse proxy)
  8. Configure backup strategy for all data volumes
  9. Consider using managed PostgreSQL (AWS RDS, Google Cloud SQL)
  10. Configure Keycloak for production (realm export, email verification)

Combining Multiple Data Model Apps

This SDC4 project is designed to host multiple data model applications.

Adding a New Data Model App

The easiest way to add a new data model app is using the automated installer:

Using Management Command (CLI):

# Copy the downloaded ZIP file to your project directory, then run:
docker compose exec web python manage.py install_app /app/path/to/app.zip

# Or with Podman:
podman-compose exec web python manage.py install_app /app/path/to/app.zip

Using Django Admin (Web UI): 1. Access Django Admin: http://localhost:18000/admin/ 2. Navigate to "SDC4 Tools" → "Install App from ZIP" 3. Upload your generated app ZIP file 4. The installer will automatically: - Extract and copy the app to the project - Copy all schema files (dm-.xsd, dm-.ttl, dm-.rdf, dm-_shacl.ttl) to mediafiles/dmlib/ - Update settings.py (add to INSTALLED_APPS) - Update urls.py (add URL patterns) - Run database migrations - Upload RDF data to GraphDB triplestore with OWL 2 reasoning 5. Restart your server: bash docker compose restart web

The home page will automatically detect and list all installed apps!

Method 2: Manual Installation (Alternative)

If you prefer manual control or troubleshooting:

  1. Generate the app from SDCStudio (it will be a separate Django app folder)
  2. Extract the ZIP file
  3. Copy the app folder from sdc_project/{app_name}/ into this project directory
  4. Copy all dm-. files: Copy all dm-{ct_id}.* files (xsd, ttl, rdf, shacl, html, gql) from the ZIP's mediafiles/dmlib/ folder to this project's mediafiles/dmlib/ directory
  5. Update settings.py: Add the app name to INSTALLED_APPS
  6. Update urls.py: Add the app's URL configuration: python path('newapp/', include('newapp.urls', namespace='newapp')),
  7. Run migrations: bash docker compose exec web python manage.py makemigrations docker compose exec web python manage.py migrate
  8. Upload RDF to GraphDB (optional but recommended): bash docker compose exec web python manage.py init_graphdb
  9. Restart: bash docker compose restart web

Benefits of Multi-App Projects

Project Structure

Troubleshooting

GraphDB Not Starting

The Enterprise Stack requires significant memory. Ensure Docker has at least 6GB RAM allocated.

Check GraphDB logs:

docker compose logs graphdb

Keycloak Database Issues

Keycloak shares the PostgreSQL database. If Keycloak fails to start:

docker compose down
docker compose up -d --build postgres
# Wait for PostgreSQL to be ready
docker compose up -d --build keycloak

SirixDB Certificate Errors

SirixDB uses self-signed certificates by default. For development: - Set SIRIX_VERIFY_SSL=false in .env

For production: - Configure proper SSL certificates for SirixDB

Permission Errors with Volumes

# Fix ownership of data directories
sudo chown -R 1000:1000 ./mediafiles/graphdb
sudo chown -R 1000:1000 ./mediafiles/sirixdb
sudo chown -R 999:999 ./mediafiles/postgres

Container Name Conflicts

If running multiple apps: 1. Stop other apps: docker compose down 2. Customize APP_NAME in .env to make names unique

About This Application

This application was generated from an SDC4-compliant data model using SDCStudio AppGen (Enterprise Stack).

Key Features: - Semantic data model with OWL 2 reasoning (GraphDB) - Temporal versioning and time-travel queries (SirixDB) - Enterprise SSO/RBAC authentication (Keycloak) - PostgreSQL for operational data storage - Celery for background task processing - Auto-generated forms matching your data model - Bulk import for XML instance files - Docker/Podman compatible deployment

Bulk Import (Staff Only)

Each data model app includes a Bulk Import feature for importing multiple XML instance files at once. This feature is only available to staff users (users with is_staff=True).

Accessing Bulk Import

  1. Login to Django Admin: http://localhost:18000/admin/
  2. Navigate to your app's list page
  3. The Bulk Import link appears in the navigation bar (staff users only)

Import Methods

Option 1: Upload ZIP File - Create XML instance files following the template format - Package them into a ZIP file - Upload via the Bulk Import page

Option 2: Server Directory Path (Recommended for batch imports) - Place XML files in the import_data/{app_name}/ folder next to docker-compose.yml - Each app has its own subdirectory (e.g., import_data/civil_registry/, import_data/healthcare_record/) - The directory is volume-mounted into the container at /import_data/{app_name}/ - The form pre-fills with the correct default path for each app - Example directory structure: sdc4/ ├── docker-compose.yml ├── import_data/ │ ├── civil_registry/ # XML files for Civil Registry app │ │ ├── person_001.xml │ │ ├── person_002.xml │ │ └── ... │ ├── vital_statistics/ # XML files for Vital Statistics app │ │ └── ... │ ├── business_registry/ # XML files for Business Registry app │ │ └── ... │ ├── property_registry/ # XML files for Property Registry app │ │ └── ... │ ├── education_record/ # XML files for Education app │ │ └── ... │ ├── employment_record/ # XML files for Employment app │ │ └── ... │ ├── tax_revenue/ # XML files for Tax & Revenue app │ │ └── ... │ ├── maritime/ # XML files for Maritime app │ │ └── ... │ ├── healthcare_record/ # XML files for Healthcare app │ │ └── ... │ └── law_enforcement/ # XML files for Law Enforcement app │ └── ...

XML Template

Click Download XML Template on the Bulk Import page to get a skeleton XML file showing the expected format for your data model. Each XML file represents one record.

Import Process

  1. XML files are validated against the data model's XSD schema
  2. Valid records are created in the database with RDF uploaded to GraphDB
  3. Invalid files are still saved but marked with invalid status and an inv_ filename prefix for easy identification
  4. Instance IDs are auto-generated (format: i-{cuid}) — any existing instance_id in the XML is replaced
  5. Creation timestamps are updated to the current time on import
  6. Duplicate detection: Files whose content matches an existing record (ignoring instance_id and timestamp) are automatically skipped
  7. Import results show success, failure, and skipped (duplicate) counts with per-file details

Best Practices

Learn more: - SDCStudio: https://axius-sdc.com - Semantic Data Charter: https://semanticdatacharter.com

← Back to Home