Documentation & Getting Started

This documentation guides you through the setup and practical application of the ONDEMANDENV platform — a contract-orchestration layer for distributed systems on AWS. Services declare their interfaces as typed code in a ContractsLib; the platform enforces compatibility at compile time and automates deployment in dependency order. See the Platform page for a conceptual overview before diving in here.

Installation & Setup

Follow these steps to set up the ONDEMANDENV platform in your environment.

1. Environment Preparation

AWS Environment:

AWS Organization: Set up an AWS Organization.
Two AWS Accounts: Within your organization, designate or create:
- A Central Account: This is where the core ONDEMANDENV platform engine will run.
- A Workspace Account (workspace0): The initial target for deployments, including the mandatory contractsLib enver.
Hosted Zone: Create a public hosted zone in Route 53 within the Central Account. Choose a suitable domain name, for example: <your-chosen-name>.root.ondemandenv.link. Note this name, as you will need it later.
Region: Decide on the primary AWS region (e.g., us-east-1). All initial setup resources should be in this region.

AWS CDK Bootstrap: Bootstrap CDK in both the Central Account and the workspace0 account for your chosen region. Run:

# In Central Account context
aws configure set region YOUR_REGION
cdk bootstrap aws://CENTRAL_ACCOUNT_ID/YOUR_REGION

# In workspace0 Account context
aws configure set region YOUR_REGION
cdk bootstrap aws://WORKSPACE0_ACCOUNT_ID/YOUR_REGION

Cross-Account Trust: Configure the workspace0 account to trust the Central Account. Create an IAM role in workspace0 (e.g., OndemandenvDeployerRole) with AdministratorAccess (or a more restricted policy based on least privilege later) that the Central Account can assume. The trust policy should explicitly allow the role ARN that the ONDEMANDENV platform will use in the Central Account (this will be defined by the platform template).
GitHub App Private Key Secret: Create a secret in AWS Secrets Manager within the Central Account. Choose a specific name for this secret (e.g., ondemandenv/github-app-private-key). You will store your GitHub App's private key here in the next step. Note this secret name (ghAppPrivateKeySecretName). The ONDEMANDENV platform template will require this name.

GitHub Environment:

GitHub Organization: Ensure you have a GitHub Organization set up.
Private GitHub App: Create a new, private GitHub App owned by your organization.
- Download the generated private key (.pem file).
- Important: Store the contents of this private key file securely as a new version in the AWS Secrets Manager secret (ghAppPrivateKeySecretName) you created in the Central Account.
- Configure necessary permissions for the App (refer to ONDEMANDENV documentation for specifics, typically includes read access to code, metadata, and write access for issues, pull requests, workflows, checks, statuses, deployments).
- Leave the Webhook URL blank for now; you will update this after deploying the platform.
- Install this GitHub App on the specific repository you intend to use for your contractsLib.
contractsLib Repository: Create a repository within your GitHub Organization to define your service contracts. This repository will contain your ONDEMANDENV build and enver definitions.
- You can use ondemandenv/odmd-contracts-sandbox as an example structure.
- Ensure your repository includes necessary dependencies (like @ondemandenv.dev/contracts-lib-base) and build scripts (e.g., in package.json) to compile your TypeScript definitions. The @ondemandenv.dev/contracts-lib-base package provides the core interfaces and base classes that your specific contractsLib will implement and extend.
- You will need to package your compiled contractsLib definition using npm pack. This generates a .tgz file.

2. Platform Deployment

Submit Information to ONDEMANDENV Service: You will need to provide the following information to the ONDEMANDENV service team (e.g., via email or a setup portal):
- Your packaged contractsLib definition file (.tgz).
- The name of the hosted zone you created (e.g., <your-chosen-name>.root.ondemandenv.link).
- Your AWS Central Account ID.
- The name you chose for the GitHub App private key secret (ghAppPrivateKeySecretName).
- The GitHub App ID.
Receive and Deploy Platform Template: The ONDEMANDENV service team will use this information to prepare the core infrastructure template. They will send back a CloudFormation template file (e.g., odmd--central-artifact.template.json). Deploy this template into your Central Account using the AWS Console or CLI.
```
aws cloudformation deploy \
    --template-file path/to/odmd--central-artifact.template.json \
    --stack-name odmd-central-platform \
    --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM \
    --region YOUR_REGION
```
(Note: Parameter overrides might be required depending on the template structure.)
Important Notes on Resource Sharing:
- S3 Bucket for Artifacts: This stack will provision or configure an S3 bucket. This bucket is used by the platform (and potentially your CI/CD workflows) to store deployment artifacts like CloudFormation templates. Ensure its policy allows access as needed by the ONDEMANDENV service backend.
- SQS Queue for Notifications: The template configures integration with an SQS queue provided by the ONDEMANDENV service. Your deployed stack resources (e.g., Lambda functions) will poll or be triggered by messages from this queue to receive notifications or commands from the platform.
Configure GitHub App Webhook:
- Wait for the CloudFormation stack (odmd-central-platform or similar name based on the template) to complete deployment successfully.
- Within the stack outputs, find the output named GithubWebHookUrl (or similar).
- Go back to your GitHub App settings page on GitHub.
- Paste this URL into the "Webhook URL" field.
- Configure a Webhook secret if required by the platform template and enter it in the GitHub App settings.
- Ensure the webhook is set to "Active".

Once these steps are complete, the core ONDEMANDENV platform should be running in your Central Account and connected to your GitHub App. You can then proceed to the Core Workflow section to learn how to define and deploy your services.

Core Workflow: Contract-First Development

Every service starts in ContractsLib — contracts are declared before any implementation is written. The platform derives what to build, in what order, and triggers downstream rebuilds automatically when dependencies change.

1. Define in ContractsLib

For each service, define an OdmdBuild (links to a GitHub repo) and one or more OdmdEnver instances (mock, dev, main). Each enver declares its producers (outputs it publishes) and consumers (upstream dependencies). Wire cross-build consumers after all builds exist.

Key types:

OdmdCrossRefProducer — an output this enver publishes (e.g., a base URL). Attach a schema artifact child with { children: [{ pathPart: 'schema-url', s3artifact: true }] }.
OdmdCrossRefConsumer — a dependency on another enver's producer. The platform resolves the value via SSM at deploy time.
SRC_Rev_REF('b', 'mock') — a branch revision reference. Use 't' for tag (immutable) envers.

Example (contracts-lib/src/order-manager.ts):

import { App } from 'aws-cdk-lib';
import {
  OndemandContracts, OdmdBuild, OdmdEnverCdk,
  OdmdCrossRefProducer, OdmdCrossRefConsumer, SRC_Rev_REF
} from '@ondemandenv.dev/contracts-lib-base';

// Producer enver: declares what this service publishes
export class OrderEnver extends OdmdEnverCdk {
  readonly orderApiBaseUrl: OdmdCrossRefProducer<OrderEnver>;

  constructor(owner: OrderBuild, account: string, region: string, rev: SRC_Rev_REF) {
    super(owner, account, region, rev);
    // Publish base URL + schema artifact as a child
    this.orderApiBaseUrl = new OdmdCrossRefProducer(this, 'orderApiBaseUrl', {
      children: [{ pathPart: 'schema-url', s3artifact: true }]
    });
  }

  getRevStackNames(): string[] { return ['OdmdOrderManager']; }
}

export class OrderBuild extends OdmdBuild<OrderEnver> {
  protected initializeEnvers(): void {
    this._envers = [
      new OrderEnver(this, this.contracts.accounts.workspace0, 'us-east-1', new SRC_Rev_REF('b', 'mock')),
      new OrderEnver(this, this.contracts.accounts.workspace0, 'us-east-1', new SRC_Rev_REF('b', 'dev')),
      new OrderEnver(this, this.contracts.accounts.workspace0, 'us-east-1', new SRC_Rev_REF('b', 'main')),
    ];
  }
}

// Consumer enver: declares dependencies on upstream producers
export class PaymentEnver extends OdmdEnverCdk {
  readonly orderApiBaseUrl: OdmdCrossRefConsumer<PaymentEnver, OrderEnver>;

  constructor(owner: PaymentBuild, account: string, region: string, rev: SRC_Rev_REF,
              orderEnver: OrderEnver) {
    super(owner, account, region, rev);
    this.orderApiBaseUrl = new OdmdCrossRefConsumer(this, 'orderApiBaseUrl', orderEnver.orderApiBaseUrl);
  }
}

Commit, PR, Merge: Merging to ContractsLib triggers its pipeline, which publishes the updated package and notifies the platform. The platform generates or updates the GitHub Actions workflow for each affected service repo.

2. Implement the Service

Each service repo initializes ContractsLib, resolves its target enver by env vars (ODMD_build_id, ODMD_rev_ref), and derives stack names from enver.getRevStackNames() — never hardcode revision labels in stack or resource names.

How-To: Publish outputs (OdmdShareOut)

One OdmdShareOut per stack, passing a Map of producer → value pairs. Also call deploySchema() to publish the OpenAPI/AsyncAPI artifact to S3 under the schema-url child.

How-To: Read upstream values

Call consumer.getSharedValue(scope) on your OdmdCrossRefConsumer during CDK synth to resolve the upstream SSM parameter. Internally this constructs an OdmdShareIn for you — you don't instantiate it directly.

// order-manager-service/bin/cdk.ts
import * as cdk from 'aws-cdk-lib';
import { MyOrgContracts } from '@my-org/contracts-lib';
import { OrderManagerStack } from '../lib/order-manager-stack';

const app = new cdk.App();
async function main() {
  const account = process.env.CDK_DEFAULT_ACCOUNT!;
  const region  = process.env.CDK_DEFAULT_REGION!;
  new MyOrgContracts(app);
  const enver = (MyOrgContracts as any).inst.getTargetEnver() as any;
  const [stackName] = enver.getRevStackNames();
  new OrderManagerStack(app, stackName, { env: { account, region }, enver });
}
main().catch(e => { console.error(e); process.exit(1); });

// order-manager-service/lib/order-manager-stack.ts
import * as cdk from 'aws-cdk-lib';
import * as apigwv2 from 'aws-cdk-lib/aws-apigatewayv2';
import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import { OdmdShareOut, deploySchema } from '@ondemandenv.dev/contracts-lib-base';
import { OrderEnver } from '@my-org/contracts-lib';

export class OrderManagerStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props: cdk.StackProps & { enver: OrderEnver }) {
    super(scope, id, props);
    const { enver } = props;

    // Read upstream value (e.g., auth service base URL consumed by this enver)
    // const authBaseUrl = enver.authApiBaseUrl.getSharedValue(this);

    const handler = new lambda.Function(this, 'Handler', {
      runtime: lambda.Runtime.NODEJS_22_X,
      code: lambda.Code.fromAsset('.build/handler'),
      handler: 'index.handler',
    });

    const api = new apigwv2.HttpApi(this, 'Api');
    api.addRoutes({
      path: '/orders',
      methods: [apigwv2.HttpMethod.POST],
      integration: new HttpLambdaIntegration('OrderInt', handler),
    });

    // Publish base URL — single OdmdShareOut per stack
    new OdmdShareOut(this, new Map([
      [enver.orderApiBaseUrl, api.apiEndpoint],
    ]));

    // Publish OpenAPI schema artifact under the schema-url child
    const schemaJson = require('fs').readFileSync('.build/openapi.json', 'utf8');
    const artifactBucket = /* import by name from SSM or props */ null as any;
    deploySchema(this, schemaJson, enver.orderApiBaseUrl.children![0], artifactBucket);
  }
}

3. Deploy and Iterate

Once your service is implemented, push to the branch whose name matches a declared enver revision. The platform runs .scripts/build.sh, synthesizes CDK stacks, and deploys them in the order from getRevStackNames().

Key Actions & Triggers:

Code Change Trigger: Pushing commits to a branch in the service repository triggers the deployment pipeline **if** that branch corresponds to a Branch Enver defined in contractsLib (e.g., pushing to dev triggers the 'ServiceNameDev' Enver pipeline).
Dependency Update Trigger: If an Enver consumes a Product from another Enver (Producer), an update to that consumed Product (i.e., the Producer deploys a new version) will automatically trigger a deployment of the consuming Enver to ensure it uses the latest dependency version.
Monitoring Deployment: Monitor the deployment process (triggered by any of the above) in the GitHub Actions tab (or your configured CI/CD system) of the service repository.
Verification: Verify the successful deployment by checking the AWS CloudFormation stack status and relevant resources in the target account, or by interacting with the deployed service endpoint.
Iteration: Continue iterating by pushing code changes, which will trigger subsequent automated deployments.

4. Evolve and Experiment with Clones

To test changes or experiment without destabilizing existing envers, create a dynamic clone via a commit message. The clone inherits the dependency graph of its source enver and gets unique resource names to prevent conflicts.

Key Actions:

Define Clone in contractsLib: In your contractsLib repository, define a new Enver that clones an existing one. Specify the source Enver, the new target environment, and any additional configuration.
Trigger Cloning: Trigger the cloning process by merging the changes into the contractsLib repository.
Monitor Cloning: Monitor the cloning process in the GitHub Actions tab of the contractsLib repository.
Verify Cloning: Verify the successful cloning by checking the AWS CloudFormation stack in the target account.

5. Clean Up Evolved Clones

Ephemeral environments should be short-lived. Once an experiment is complete, the cloned enver can be destroyed, ensuring no resources are left behind.

Key Actions:

Remove from `contractsLib`: In your contractsLib repository, remove the definition of the cloned Enver.
Trigger Deletion: Trigger the deletion process by merging the changes into the contractsLib repository.
Monitor Deletion: Monitor the deletion process in the GitHub Actions tab of the contractsLib repository.
Verify Deletion: Verify the successful deletion by checking that the AWS CloudFormation stack has been deleted in the target account.

Dynamic/Ephemeral Cloning

In addition to static clones defined in contractsLib, ONDEMANDENV supports dynamic, ephemeral cloning for rapid development and testing. These clones are temporary environments that can be created and destroyed on-demand.

Method 1: Manual Clone Commands

Create dynamic clones using special commands in Git commit messages:

Creating a Dynamic Clone:

Create Feature Branch: Create a new feature branch from your base branch:

git checkout -b feature/new-feature
# Make your code changes
git add .
git commit -m "Implement new feature

odmd: create@myServiceDev"

Push to Trigger Clone: Push your branch to trigger the platform:
```
git push origin feature/new-feature
```
Platform Creates Clone: ONDEMANDENV automatically:
- Creates a dynamic Enver for your feature branch
- Inherits dependency versions from the source Enver
- Deploys isolated infrastructure with unique resource names
- Provides endpoints for your isolated environment

Deleting a Dynamic Clone:

git commit --allow-empty -m "Cleanup feature environment

odmd: delete"
git push origin feature/new-feature

Method 2: Automated PR-Based Cloning

ONDEMANDENV provides fully automated cloning that integrates seamlessly with Pull Request workflows:

Automated Workflow:

Create Feature Branch & Push: Create and push your feature branch as usual:

git checkout -b feature/user-dashboard
# Make your changes
git commit -m "Redesign user dashboard"
git push origin feature/user-dashboard

Create Pull Request: Create a PR targeting a branch with a static Enver:

gh pr create --base dev --head feature/user-dashboard \
  --title "User Dashboard Redesign" \
  --body "Implements new responsive design"

Automatic Clone Creation: When the PR targets a branch with a static Enver in contractsLib, the platform automatically:
- Detects the PR creation
- Creates a dynamic Enver for the PR branch
- Deploys the isolated environment
- Updates the PR with environment details
Automatic Updates: Additional commits to the PR branch automatically update the dynamic environment
Automatic Cleanup: When the PR is closed or merged, the platform automatically destroys the dynamic Enver and cleans up all resources

Benefits of Dynamic Cloning:

Isolated Testing: Each feature gets its own complete environment
Dependency Consistency: Clones inherit exact dependency versions from source Envers
Resource Isolation: Unique resource naming prevents conflicts
Automatic Cleanup: No forgotten environments consuming resources (especially with PR-based method)
Rapid Iteration: Quick environment provisioning for fast feedback cycles
Full Stack Testing: Complete infrastructure and application testing in isolation

Requirements for PR-Based Automation:

Static Enver Mapping: Target branch must have a corresponding static Enver in contractsLib
GitHub App Permissions: Platform needs appropriate permissions to monitor PR events
Branch Name Matching: PR target branch names must match Git branch references in static Enver definitions

Comparison of Dynamic Cloning Methods:

Aspect	Manual Commands	PR-Based Automation
Trigger	odmd: create@ in commit	PR creation against static Enver branch
Cleanup	odmd: delete in commit	PR closure (merge/close)
Use Case	Ad-hoc testing, experimentation	Standard development workflow
Automation Level	Manual control	Fully automated
Integration	Git commits	GitHub/GitLab workflow

Use Platform Services

The ONDEMANDENV platform provides additional services to enhance your development and deployment experience.

Key Services:

ONDEMANDENV Console: A web-based interface that visualizes your environments, builds, and their relationships. It provides real-time versioning information, status monitoring, and Enver details. Access it at web.auth.ondemandenv.link.
CI/CD Integration: Seamless integration with your preferred CI/CD tools (e.g., GitHub Actions) to automate the deployment process.
Isolated Testing: Isolate your tests in dedicated environments to ensure they don't interfere with production or other development efforts.
Shared Networking: Share networking resources across Envers to optimize costs and improve performance.
Shared EKS: Share a single Elastic Kubernetes Service (EKS) cluster across multiple Envers for better resource utilization and cost savings.

Deployment Model

The ONDEMANDENV platform follows a unique deployment model that combines the benefits of both monolithic and microservices architectures.

Key Concepts:

Envers: An Enver represents a logical environment or version of a service. It can be a branch, a tag, or a specific configuration. Envers are defined in the contractsLib repository.
Builds: A build is the process of packaging and preparing the service for deployment. Builds are defined in the contractsLib repository.
Producers & Consumers: Producers are Envers that publish shared outputs (products) that other Envers (consumers) can consume. This enables a modular and decoupled architecture.
Deployment Workflow: The platform automates the deployment process, including building the service, packaging the artifacts, and deploying the infrastructure.

Benefits:

Modularity: Services are decoupled and modular, allowing for independent development and deployment.
Isolation: Envers are isolated from each other, ensuring that changes in one environment don't affect others.
Scalability: The platform can handle a large number of Envers and builds, supporting both small and large-scale deployments.
Flexibility: Envers can be cloned to create new environments with different configurations or targets.
Cost Optimization: Shared resources and infrastructure can lead to cost savings compared to traditional microservices architectures.

Security Considerations

Security is a top priority in the ONDEMANDENV platform. Here are some key security considerations:

Access Control:

Role-Based Access Control (RBAC): Fine-grained access control is implemented using IAM roles and policies.
Least Privilege: Principals are granted the minimum permissions necessary to perform their tasks.
Separation of Duties: Different roles are responsible for different aspects of the platform, reducing the risk of unauthorized access.

Data Protection:

Encryption at Rest: Sensitive data is encrypted at rest using AWS Key Management Service (KMS).
Encryption in Transit: Data is encrypted in transit using SSL/TLS.
Data Isolation: Envers are isolated from each other, ensuring that data from one environment doesn't leak into another.

Infrastructure Security:

Network Isolation: Envers are isolated using VPCs, subnets, and security groups.
Intrusion Detection: AWS services like AWS GuardDuty and AWS Inspector are used for intrusion detection and vulnerability scanning.
Patch Management: Automated patch management is implemented using AWS Systems Manager.

Compliance:

SOX Compliance: The platform is designed to meet the requirements of the Sarbanes-Oxley Act (SOX).
HIPAA Compliance: The platform is designed to meet the requirements of the Health Insurance Portability and Accountability Act (HIPAA).
PCI DSS Compliance: The platform is designed to meet the requirements of the Payment Card Industry Data Security Standard (PCI DSS).

CI/CD Integration

The ONDEMANDENV platform integrates seamlessly with your preferred CI/CD tools to automate the deployment process.

Key Features:

GitHub Actions: The platform is designed to work with GitHub Actions, allowing you to define and automate your CI/CD workflows directly in your contractsLib repository.
Customizable Workflows: You can customize the CI/CD workflows to meet your specific needs, including testing, building, and deploying.
Integration with ONDEMANDENV Console: The CI/CD workflows are integrated with the ONDEMANDENV Console, providing real-time visibility into the deployment process.
Isolated Testing: The platform supports isolated testing environments, ensuring that your tests don't interfere with production or other development efforts.

Example Workflow:

Trigger: A change is merged into the dev branch of the service repository.
Build: The CI/CD workflow is triggered, and the service is built using the specified build configuration.
Test: The service is tested in an isolated environment to ensure it functions correctly.
Deploy: If the tests pass, the service is deployed to the dev Enver.
Notify: The ONDEMANDENV Console is notified of the successful deployment, and the status is updated.

Base Library

The platform base library is published as @ondemandenv.dev/contracts-lib-base. It supplies the TypeScript base classes that every organization's ContractsLib extends: OndemandContracts, OdmdBuild, OdmdEnverCdk, OdmdCrossRefProducer, OdmdCrossRefConsumer, OdmdShareOut, OdmdShareIn, and SRC_Rev_REF.

Your organization's ContractsLib (e.g., odmd-contracts-sandbox) extends these base classes to define your specific accounts, GitHub repos, and service graph. All service repos then depend on your ContractsLib package (not the base directly) and must pin aws-cdk-lib to the exact same version as your ContractsLib.

Platform built-ins your ContractsLib can optionally include: __user-auth (Google OAuth → AWS Cognito → IAM), __networking (shared VPC/TGW), _default-vpc-rds, _default-kube-eks. The __contracts build (ContractsLib itself) is mandatory — it is always the first enver, serving all regions.

Minimal ContractsLib skeleton:

import { App } from 'aws-cdk-lib';
import {
  OndemandContracts, GithubRepo, GithubReposCentralView,
  AccountsCentralView, OdmdBuildContractsLib, OdmdEnverContractsLib, SRC_Rev_REF
} from '@ondemandenv.dev/contracts-lib-base';

type MyRepos = GithubReposCentralView & { orderManager: GithubRepo; };
type MyAccounts = AccountsCentralView & { workspace1: string; };

export class MyOrgContracts extends OndemandContracts<MyAccounts, MyRepos, OdmdBuildContractsLib<any, any>> {
  constructor(app: App) { super(app, 'MyOrgContracts'); }

  get accounts(): MyAccounts {
    return { central: '111111111111', workspace0: '222222222222', workspace1: '333333333333' };
  }
  get githubRepos(): MyRepos {
    const ghAppInstallID = 12345678;
    return {
      githubAppId: '123456',
      __contracts: { owner: 'my-org', name: 'contracts-lib', ghAppInstallID },
      orderManager: { owner: 'my-org', name: 'order-manager', ghAppInstallID },
    };
  }
}

Explore the Code

The ONDEMANDENV platform is open source, and its code is available on GitHub. You can explore the code and contribute to its development.

Key Repositories:

Platform Core: github.com/ondemandenv/odmd-platform-core
Base Library: github.com/ondemandenv/odmd-contracts-base
Example Contracts: github.com/ondemandenv/odmd-contracts-sandbox

Contributing:

We welcome contributions to the ONDEMANDENV platform. If you're interested in contributing, please review our Contributing Guidelines.

Platform Internals

This section provides an overview of the internal workings of the ONDEMANDENV platform.

Architecture:

The platform is built on a microservices architecture, with separate services responsible for different aspects of the platform. The main services include:

Contracts Service: Manages the contractsLib repository and generates the CI/CD workflows.
Build Service: Builds the service artifacts based on the build configuration.
Deployment Service: Deploys the service artifacts to the target environment.
Console Service: Provides the ONDEMANDENV Console web interface.

Data Flow:

The data flow within the platform is as follows:

Contracts: The contractsLib repository defines the contracts for the platform, including the build configurations and Enver definitions.
CI/CD Workflows: The Contracts Service generates the CI/CD workflows based on the contracts.
Build: The Build Service builds the service artifacts based on the build configuration.
Deployment: The Deployment Service deploys the service artifacts to the target environment.
Console: The Console Service provides real-time visibility into the platform, including the status of Envers and the relationships between them.

Security:

The platform implements various security measures to ensure the confidentiality, integrity, and availability of the data and services. For more details, refer to the Security Considerations section.

Scalability:

The platform is designed to scale horizontally, allowing it to handle a large number of Envers and builds. The services are stateless and can be scaled independently based on the workload.

Reliability:

The platform is designed to be highly reliable, with redundant components and automated failover mechanisms. The services are deployed across multiple availability zones to ensure high availability.

ONDEMANDENV Console

Overview

The ONDEMANDENV Console serves as the primary user interface for visualizing and interacting with your environments, builds, and their relationships within the platform. After logging in (typically via Google OAuth integrated with your organization's identity provider), the console connects securely to the central AppSync API in your AWS environment.

Its main focus is to provide clarity on the complex web of dependencies inherent in distributed systems, leveraging the information codified in your contractsLib.

Console Authentication Setup

To enable user authentication for the console, you will need to configure Google OAuth 2.0. This process involves:

Setting up an OAuth 2.0 client ID in the Google Cloud Console.
Obtaining a Google Client ID and a Google Client Secret.
These credentials must then be securely incorporated into your contractsLib definitions. This typically involves referencing them as secure parameters or secrets that the console's backend infrastructure (defined via an Enver in contractsLib) can access.
For an example of how these credentials are referenced within contractsLib for a user authentication service that the console would rely on, see the OdmdBuildUserAuthSbx.ts example in the sandbox contracts. This example file typically extends a base authentication contract class (e.g., odmd-build-user-auth.ts) from the @ondemandenv.dev/contracts-lib-base library, demonstrating how your specific console authentication setup connects with the central platform logic, often involving services like AWS AppSync.

Proper configuration of these OAuth credentials and their integration into your contractsLib is essential for the console's login functionality and secure access to real-time data.

Key Features

Dependency Visualization: Clearly shows how builds (producers) and Envers (consumers) depend on each other, based on the contracts defined in contractsLib.
Real-time Versioning Information: Connects to AWS AppSync in the central account to fetch live data about all producer build versions and consumer Enver deployments.
Status Monitoring: Indicates whether a consumer Enver is using an up-to-date version of a producer build, is lagging behind, or if a required dependency hasn't been deployed yet.
Enver Details: Displays specific details for each Enver, such as the exact version of the contractsLib it's using, derived from real-time AWS Stack summaries.
Secure Access: Uses Google OAuth for authentication, ensuring only authorized users can access the console and system data.

Example Access

You can explore a live example of the ONDEMANDENV console configured for the demonstration organization hosted on GitHub (github.com/ondemandenv). Access it here:

Example Console (web.auth.ondemandenv.link)

Note: Access to specific data within the example console may require appropriate permissions tied to the example organization's authentication setup.

Support

If you need help or have any questions about the ONDEMANDENV platform, please don't hesitate to reach out to our support team.

Contact Information:

Email: [email protected]

Additional Resources:

Documentation: ONDEMANDENV Documentation
GitHub: ONDEMANDENV GitHub Organization