specmatic/specmatic-insights repository overview

⁠Specmatic Insights

⁠Getting Started with Specmatic Insights

This guide will help you quickly set up and run Specmatic Insights using Docker.

⁠Overview

Specmatic Insights is an application that unlocks insights into your microservices, helps you track dependencies, and spot problems early. It aggregates and visualizes service interactions across different environments, providing an "x-ray view" of your microservices architecture.

⁠Key Features

• Service Mesh Visualization: See your entire service ecosystem in interconnected graphs
• Contract Standards Support: Works with OpenAPI, WSDL, and AsyncAPI specifications
• Integration Health Tracking: Identify bottlenecks and integration issues before they affect users
• Dependency Management: Track all service dependencies in one centralized dashboard
• Contract-Driven Development: Monitor and measure CDD adoption across your organization

This Docker image includes a trial license that enables you to ingest 10 total API operations.

⁠Prerequisites

• Docker & Docker Compose: Installed on your machine
• MariaDB: The Insights app requires a MariaDB database

⁠Quick Start

⁠1. Set Up the Database

The Insights app requires a MariaDB database. You can run it using Docker:

docker run -d \
  --name insights-db \
  -e MARIADB_ROOT_PASSWORD=admin \
  -e MARIADB_DATABASE=insights \
  -e MARIADB_USER=insights_user \
  -e MARIADB_PASSWORD=foobar \
  -p 3306:3306 \
  mariadb:11.7.2

⁠2. Run the Specmatic Insights

Pull and run the Specmatic Insights image:

docker run -d \
  --name specmatic-insights \
  -p 8080:8080 \
  -e SPRING_DATASOURCE_URL=jdbc:mariadb://host.docker.internal:3306/insights \
  -e SPRING_DATASOURCE_USERNAME=insights_user \
  -e SPRING_DATASOURCE_PASSWORD=foobar \
  specmatic/specmatic-insights:latest

If you're using Docker Compose, you can use the following docker-compose.yml file:

services:
  db:
    image: mariadb:11.7.2
    container_name: insights_db
    restart: always
    environment:
      MARIADB_ROOT_PASSWORD: admin
      MARIADB_DATABASE: insights
      MARIADB_USER: insights_user 
      MARIADB_PASSWORD: foobar
    ports:
      - "3306:3306"
    volumes:
      - mariadb_data:/var/lib/mysql
    networks:
      - insights-network

  insights-app:
    image: specmatic/specmatic-insights:latest
    container_name: insights_app
    restart: always
    depends_on:
      - db
    environment:
      SPRING_PROFILES_ACTIVE: prod
      SPRING_DATASOURCE_URL: jdbc:mariadb://db:3306/insights
      SPRING_DATASOURCE_USERNAME: insights_user
      SPRING_DATASOURCE_PASSWORD: foobar
      # Uncomment below when using SAML
      # Relying Party (Service Provider) configuration
      # SAML_RELYING_PARTY_PRIVATE_KEY_LOCATION: file:/config/keys/localhost.key
      # SAML_RELYING_PARTY_CERTIFICATE_LOCATION: file:/config/certs/localhost.pem
    ports:
      - "8080:8080"
    # Uncomment below when using SAML
    # volumes:
    #  - /path/to/keys:/config/keys/
    #  - /path/to/certs:/config/certs/
    networks:
      - insights-network

volumes:
  mariadb_data:

networks:
  insights-network:
    driver: bridge

Run with:

docker-compose up -d

⁠Trial License Information

The Docker image includes a trial license that allows for ingesting 10 total API operations. This is sufficient for testing and evaluation purposes. For production use, you'll need to acquire a full license: https://insights.specmatic.io/contact/⁠.

⁠Accessing your Specmatic Insights

The application comes with a bundled web interface. To access the dashboard, visit:

http://localhost:8080/dashboard

⁠Configuration Options

The Specmatic Insights app can be configured using the following environment variables:

⁠Troubleshooting

⁠Database Connection Issues

If the app fails to connect to the database, check the following:

1. Ensure the database container is running:

   docker ps | grep insights_db
   

   Copy

2. Verify the database credentials are correct

3. Check the logs for any connection errors:

   docker logs insights_app
   

   Copy

⁠License Issues

If you encounter license-related errors:

1. The trial license allows for 10 API operations only
2. Check the logs to see if you've exceeded this limit
3. Contact Specmatic⁠ to obtain a full license for continued use

⁠Next Steps

After you have the app running successfully:

1. Access the bundled web interface by navigating to the dashboard⁠ in your browser
2. You will be prompted to login - if this is your first time, you can register and create a test organization to help you explore Insights
3. Navigate through the dashboard to explore the features and capabilities of Specmatic Insights
4. Integrate Specmatic into your CI/CD pipelines to collect contract validation reports
5. Set up continuous specification validation for your microservices
6. Use the insights dashboard to improve service integration and communication
7. Consider obtaining a full license for production use once you've completed your evaluation

⁠Integration with CI/CD Pipelines

Specmatic Insights becomes most valuable when integrated with your CI/CD pipelines. By collecting Specmatic reports from your build processes, you can:

• Track contract compatibility across all services
• Identify breaking changes before they reach production
• Monitor contract test coverage over time
• Visualize the impact of changes across your service ecosystem

⁠How to integrate with CI/CD Pipelines

We provide first-class support for GitHub actions, and have detailed instructions on our documentation website: Setup Insights in your pipelines⁠

However, if you're not using GitHub actions, you can use send-specmatic-build-report.sh to help you integrate.

Preconditions

• npx and Node.js Availability: The system running the script must have Node.js and npx installed and accessible in the system's PATH. The script uses npx to execute specmatic-insights-github-build-reporter, which will download the package if it's not already cached.
• Report Directory Path: You need to correctly specify the path to your reports directory using the --specmatic-reports-dir (or -srd) argument. If you run the script from within the directory containing the reports, you can use --specmatic-reports-dir . If you run the script from a different directory, you'll need to provide the correct relative or absolute path to the reports directory.
• Script Location: The send-specmatic-build-report.sh script itself can be located anywhere. You'll just need to call it using its correct path (e.g., /path/to/send-specmatic-build-report.sh).

As an example, for Gitlab, the build step would look like:

# .gitlab-ci.yml

stages:
- report

send_specmatic_report:
image: node:18
stage: report
script:
- chmod +x send-specmatic-build-report.sh
- ./send-specmatic-build-report.sh

Similarly, a Jenkins groovy snippet would look like:

pipeline {
  agent any

  stages {
    stage('Send Specmatic Report') {
      steps {
        // make sure Node+npm are available on this agent
        sh '''
          chmod +x send-specmatic-build-report.sh
          ./send-specmatic-build-report.sh
        '''
      }
    }
  }
}

⁠Getting Help

If you need further assistance, please:

1. Check the Specmatic documentation⁠
2. Reach out for support⁠