.. include:: /includes.rst.txt .. _dev_test_prod_servers_best_practices: ************************************************** Best Practices for Dev, Test, and Prod EDG Servers ************************************************** .. :Version: 0.1 .. :Date: 2025-12-18 Introduction ============ This document defines best practices for operating TopBraid EDG across Development (Dev), Testing (Test / QA / UAT), and Production (Prod) environments. These practices apply to both TopBraid EDG Software-as-a-Service (SaaS) and on-premises deployments. While infrastructure and operational responsibilities may differ, governance principles, lifecycle patterns, and promotion discipline remain consistent. By following these practices, organizations can: * Enable safe experimentation and rapid iteration in Dev * Validate governance behavior and integrations in Test * Protect Production from unreviewed or unstable changes * Establish accountability and auditability for governance decisions * Support scalable, repeatable, and compliant EDG operations The intended audience includes: * EDG administrators * Ontology and model developers * Data stewards and governance leads * Platform and DevOps teams * Release and change managers A note on EDG Explorer ---------------------- Some organizations also use **TopBraid EDG Explorer** as a read-only environment for broadly published data. Explorer is typically populated from Production EDG and does not provide fine-grained access control—every user can see all published content. Explorer may act as: * A downstream integration source * A broad organizational viewing layer * A controlled publication target on a defined release cadence Environment Overview ==================== This section describes the role each EDG environment plays in the governance lifecycle and clarifies expectations around stability, access, and data usage. .. list-table:: :header-rows: 1 * - Category - Dev - Test (QA / UAT) - Prod * - Purpose - Active development and experimentation - Validation before Production - Authoritative governance system * - Characteristics - Frequent change, relaxed constraints - Production-like configuration - Stability and strict controls * - Data - Synthetic or sample data - Masked or curated Prod subsets - Authoritative governed data Governance and Operating Principles =================================== The following principles guide how EDG environments should be used and managed. .. list-table:: :header-rows: 1 * - Principle - Description - Why It Matters * - Environment Isolation - Dev, Test, and Prod are distinct systems - Reduces production risk * - Promote, Don’t Recreate - Author once, promote forward - Prevents environment drift * - Reproducibility - Every Prod change is traceable - Supports auditability and rollback * - Least Privilege - Permissions tighten toward Prod - Limits unauthorized changes * - Documentation - Promotion rules and exceptions documented - Preserves institutional knowledge Access Control and Roles ======================== Access and permissions should become progressively more restrictive as assets move toward Production. Governance authority must align with accountability. Role Definitions and Environment Access --------------------------------------- .. list-table:: :header-rows: 1 * - Role - Capabilities - Dev - Test - Prod * - Server Administrator - System configuration and maintenance - Full - Full - Full * - Power User - Limited admin and configuration - Limited - Limited - Limited * - Modeler / Technical Steward - Ontologies, SHACL, workflows - Write - Write - Write (limited) * - Developer - Automation and integrations - Write - Limited - Execute-only * - Data Steward - Asset curation and quality - Write - Write - Write via workflow * - SME - Review and approval - Read - Read - Read * - Explorer - Search and view published data - Read - Read - Read Model and Ontology Management ============================= Ontologies, vocabularies, and SHACL shapes should follow a controlled lifecycle: * Authored and iterated in Dev * Validated in Test * Promoted to Prod only when approved Best practices include: * Use unversioned URIs for classes and properties * Avoid breaking URI changes once in Prod * Deprecate instead of deleting * Keep ontologies modular to reduce promotion risk Asset Lifecycle Management ========================== .. list-table:: :header-rows: 1 * - Dev - Test - Prod * - Draft and experimental assets - Validation and steward review - Workflow-governed authoritative assets * - Incomplete metadata acceptable - UAT may be required - Deletions are rare and governed Workflow and Approval Configuration =================================== .. list-table:: :header-rows: 1 * - Dev - Test - Prod * - Design and refine workflows - Validate governance behavior - Enforce approvals strictly * - Test edge cases - Validate notifications - Changes via promotion only Data Migration and Promotion ============================ Promotion should follow deliberate, repeatable processes rather than ad-hoc activities. Detailed guidance is covered in :ref:`data_migration_best_practices`. Promotion Strategies -------------------- * Export/import at project or collection level * API-driven promotion * Git-backed artifacts where applicable What Gets Promoted ------------------ .. list-table:: :header-rows: 1 * - Promote - Do Not Routinely Promote * - Ontologies and SHACL - Transactional content * - Workflow definitions - Environment-specific data * - Governance configuration - User-generated operational data Validation and Rollback ----------------------- After promotion: * Run SHACL validation * Verify workflows and permissions * Retain backups for rollback * Validate integrations before enabling consumers Integration and Automation ========================== .. list-table:: :header-rows: 1 * - Category - Practices * - General - Environment-specific endpoints and credentials * - SaaS - Vendor-supported APIs and maintenance alignment * - On-Prem - CI/CD integration and password vaults Data Quality and Validation =========================== * Define SHACL constraints early * Enforce stricter validation toward Prod * Monitor validation failures * Use dashboards and reports for steward oversight Change Management and Release Planning ====================================== * Formal change requests for Prod * Scheduled release windows * Freeze periods when required * Clear stakeholder communication * Maintain audit trails Security and Compliance ======================= .. list-table:: :header-rows: 1 * - Category - Practices * - General - SSO, audit logs, compliance alignment * - SaaS - Shared responsibility awareness * - On-Prem - Network hardening and SIEM integration Backup, Recovery, and Environment Refresh ========================================= * Regular backups for all environments * Defined restore and refresh procedures * Validated environments after restore * Clear ownership and accountability Monitoring and Operational Support ================================== * Monitor availability and performance * Alert on validation failures * Define incident response procedures * Establish escalation paths Common Pitfalls and Anti-Patterns ================================= * Making “quick fixes” in Prod * Environment drift from manual edits * Over-permissive non-Prod access * Untested workflow changes * Treating Test as optional Dev → Test → Prod Promotion Checklist ===================================== .. list-table:: :header-rows: 1 * - Phase - Checklist * - Before Promotion - Code reviewed, SHACL validated, workflows verified * - During Promotion - Scripted process, version captured, activity logged * - After Promotion - Validation, smoke tests, stakeholder notification EDG Studio ========== EDG Studio is a desktop environment useful for isolated development of scripts, ADS logic, SHACL rules, and customizations. Key characteristics: * Completely isolated from EDG servers * Safe for experimental or destructive testing * Works well with local Git repositories and IDEs * Can be treated as a Pre-Dev environment Artifacts can be promoted from Studio to Dev when ready for team testing. For setup details, see the EDG Studio documentation.