Deploying Middleware

Introduction

Middleware is an open-source engineering management platform that helps engineering teams track DORA metrics, developer productivity, and team performance. By integrating with your existing development tools like GitHub, GitLab, Jira, and CI/CD systems, Middleware provides actionable insights into your software delivery process.

Built for engineering leaders and teams who want to improve their development practices, Middleware automatically collects data from your tools and presents it through intuitive dashboards. The platform focuses on the four key DORA metrics: Deployment Frequency, Lead Time for Changes, Mean Time to Recovery, and Change Failure Rate.

Key highlights of Middleware:

• DORA Metrics: Track the four key DevOps Research and Assessment metrics
• Git Analytics: Deep insights into code changes, PRs, and review processes
• Issue Tracking: Integration with Jira and other project management tools
• CI/CD Integration: Monitor build times, deployment frequency, and pipeline health
• Team Insights: Understand team velocity, collaboration patterns, and workload
• Custom Dashboards: Build personalized views of the metrics that matter
• Automated Collection: Continuous data sync from integrated tools
• Privacy-Focused: Self-host to keep your engineering data private
• Open Source: Transparent codebase with community contributions
• API Access: Programmatic access to all collected data

This guide walks through deploying Middleware on Klutch.sh using Docker, configuring integrations with your development tools, and setting up engineering metrics tracking.

Why Deploy Middleware on Klutch.sh

Deploying Middleware on Klutch.sh provides several advantages for engineering analytics:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Middleware without complex orchestration. Push to GitHub, and your analytics platform deploys automatically.

Persistent Storage: Attach persistent volumes for your metrics database. Your historical engineering data survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access to sensitive engineering metrics.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on your data volume and team size.

Custom Domains: Assign a custom domain for your engineering dashboard.

Always-On Availability: Your metrics platform runs 24/7, continuously collecting and processing data.

Prerequisites

Before deploying Middleware on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• A PostgreSQL database (can be deployed on Klutch.sh)
• API access to your development tools (GitHub, GitLab, Jira, etc.)
• (Optional) A custom domain for your dashboard

Preparing Your Repository

To deploy Middleware on Klutch.sh, create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

middleware-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM node:18-alpine

# Install dependencies
RUN apk add --no-cache python3 make g++ git

# Set working directory
WORKDIR /app

# Clone Middleware
RUN git clone https://github.com/middlewarehq/middleware.git . \
    && rm -rf .git

# Install dependencies
RUN npm install

# Build the application
RUN npm run build

# Set environment variables
ENV NODE_ENV=production
ENV PORT=3000

# Expose port
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

# Start the application
CMD ["npm", "start"]

Environment Variables Reference

Variable	Required	Default	Description
DATABASE_URL	Yes	-	PostgreSQL connection string
SECRET_KEY	Yes	-	Application encryption key
GITHUB_CLIENT_ID	No	-	GitHub OAuth app client ID
GITHUB_CLIENT_SECRET	No	-	GitHub OAuth app client secret
GITLAB_CLIENT_ID	No	-	GitLab OAuth app client ID
GITLAB_CLIENT_SECRET	No	-	GitLab OAuth app client secret
JIRA_CLIENT_ID	No	-	Jira OAuth app client ID
JIRA_CLIENT_SECRET	No	-	Jira OAuth app client secret

Deploying on Klutch.sh

Set Up PostgreSQL

Deploy a PostgreSQL database on Klutch.sh or use an external provider. Note the connection URL.

Generate a Secret Key

Generate a secure secret key:

openssl rand -hex 32

Create OAuth Applications

Create OAuth apps in your development tools:

• GitHub: Settings > Developer settings > OAuth Apps
• GitLab: User Settings > Applications
• Jira: Developer Console > Create OAuth app

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Middleware deployment configuration"
git remote add origin https://github.com/yourusername/middleware-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “middleware” or “eng-analytics”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Middleware Dockerfile.

Configure HTTP Traffic

Middleware serves its web interface over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

Add the following environment variables:

Variable	Value
DATABASE_URL	Your PostgreSQL connection string
SECRET_KEY	Your generated secret key
GITHUB_CLIENT_ID	Your GitHub OAuth client ID
GITHUB_CLIENT_SECRET	Your GitHub OAuth client secret

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/app/data	10 GB	Application data and cache

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Middleware container
• Provision an HTTPS certificate

Access Middleware

Once deployment completes, access your Middleware dashboard at https://example-app.klutch.sh.

Initial Setup

Creating Your Organization

1. Navigate to your Middleware instance
2. Create an account or sign in with GitHub
3. Create your organization
4. Invite team members

Connecting Integrations

Link your development tools:

1. Go to Settings > Integrations
2. Connect GitHub/GitLab for code metrics
3. Connect Jira for issue tracking
4. Connect CI/CD tools for deployment metrics
5. Configure sync settings

Understanding DORA Metrics

Deployment Frequency

How often your team deploys to production:

• Elite: Multiple deploys per day
• High: Daily to weekly
• Medium: Weekly to monthly
• Low: Monthly or less

Lead Time for Changes

Time from code commit to production:

• Elite: Less than one hour
• High: One day to one week
• Medium: One week to one month
• Low: More than one month

Mean Time to Recovery

How quickly you recover from failures:

• Elite: Less than one hour
• High: Less than one day
• Medium: One day to one week
• Low: More than one week

Change Failure Rate

Percentage of deployments causing failures:

• Elite: 0-15%
• High: 16-30%
• Medium: 31-45%
• Low: 46-100%

Dashboard Features

Team Overview

View aggregated team metrics:

• DORA metric scores
• PR cycle times
• Deployment trends
• Issue completion rates

Individual Insights

Track developer contributions:

• Code review participation
• PR authoring patterns
• Focus time vs meetings
• Collaboration networks

Custom Reports

Build custom views:

1. Select metrics to include
2. Set date ranges
3. Filter by team or project
4. Export or share

Best Practices

Data-Driven Improvement

Use metrics to drive improvement:

1. Establish baseline measurements
2. Identify bottlenecks
3. Implement targeted improvements
4. Measure impact over time

Avoiding Metric Misuse

Remember that metrics should:

• Guide conversations, not judgments
• Focus on team improvement
• Consider context and nuance
• Avoid individual comparisons

Troubleshooting

Sync Not Working

• Verify OAuth credentials
• Check API rate limits
• Review integration permissions
• Test API connectivity

Missing Data

• Confirm integrations are connected
• Check sync schedules
• Verify repository access
• Review filter settings

Incorrect Metrics

• Validate data source configuration
• Check branch protection settings
• Review deployment detection rules
• Confirm timezone settings

Additional Resources

• Middleware GitHub Repository
• Middleware Documentation
• DORA Research
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Middleware on Klutch.sh gives you a powerful engineering analytics platform that helps your team understand and improve their development practices. By tracking DORA metrics and integrating with your existing tools, Middleware provides data-driven insights into your software delivery process.

The combination of Middleware’s comprehensive analytics and Klutch.sh’s reliable infrastructure enables continuous improvement tracking without compromising on data privacy. Whether you’re an engineering manager looking to optimize team performance or a developer wanting to understand workflow patterns, Middleware on Klutch.sh provides the foundation for engineering excellence.