{"id":14033936,"url":"https://github.com/middlewarehq/middleware","last_synced_at":"2025-07-27T02:31:19.665Z","repository":{"id":231106532,"uuid":"780845743","full_name":"middlewarehq/middleware","owner":"middlewarehq","description":"✨ Open-source DORA metrics platform for engineering teams ✨","archived":false,"fork":false,"pushed_at":"2025-07-16T11:53:17.000Z","size":17039,"stargazers_count":1338,"open_issues_count":30,"forks_count":127,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-07-17T15:48:43.197Z","etag":null,"topics":["ai","artificial-intelligence","dev","dev-productivity","dev-tool","devops","dora","dora-metrics","engineering-management","engineering-productivity","hacktoberfest","pr-review","pull-request-review"],"latest_commit_sha":null,"homepage":"https://middlewarehq.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/middlewarehq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-04-02T09:14:22.000Z","updated_at":"2025-07-17T01:15:14.000Z","dependencies_parsed_at":"2024-04-02T13:49:59.558Z","dependency_job_id":"dd49074c-fea2-486b-84a2-481b407a655a","html_url":"https://github.com/middlewarehq/middleware","commit_stats":null,"previous_names":["middlewarehq/dora-metrics","middlewarehq/middleware"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/middlewarehq/middleware","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/middlewarehq%2Fmiddleware","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/middlewarehq%2Fmiddleware/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/middlewarehq%2Fmiddleware/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/middlewarehq%2Fmiddleware/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/middlewarehq","download_url":"https://codeload.github.com/middlewarehq/middleware/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/middlewarehq%2Fmiddleware/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267288872,"owners_count":24064723,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","artificial-intelligence","dev","dev-productivity","dev-tool","devops","dora","dora-metrics","engineering-management","engineering-productivity","hacktoberfest","pr-review","pull-request-review"],"created_at":"2024-08-12T03:00:34.776Z","updated_at":"2025-07-27T02:31:19.645Z","avatar_url":"https://github.com/middlewarehq.png","language":"TypeScript","readme":"\u003cbr /\u003e\u003cbr /\u003e\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://www.middlewarehq.com/\"\u003e\u003cimg src=\"https://github.com/middlewarehq/middleware/blob/main/media_files/logo.png\" alt=\"Middleware Logo\" width=300px\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cb\u003eOpen-source engineering management that unlocks developer potential\u003c/b\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://github.com/middlewarehq/middleware/actions/workflows/build.yml\"\u003e\u003cimg alt=\"continuous integration\" src=\"https://img.shields.io/github/actions/workflow/status/middlewarehq/middleware/build.yml?branch=main\u0026label=build\u0026style=for-the-badge\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/middlewarehq/middleware/graphs/commit-activity\"\u003e\u003cimg alt=\"Commit activity per month\" src=\"https://img.shields.io/github/commit-activity/m/middlewarehq/middleware?style=for-the-badge\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/middlewarehq/middleware/graphs/contributors\"\u003e\u003cimg alt=\"contributors\" src=\"https://img.shields.io/github/contributors-anon/middlewarehq/middleware?color=yellow\u0026style=for-the-badge\" /\u003e\u003c/a\u003e\n\u003cbr/\u003e\n\u003ca href=\"https://opensource.org/licenses/Apache-2.0\"\u003e\u003cimg src=\"https://img.shields.io/badge/apache%202.0-purple.svg?style=for-the-badge\u0026label=license\" alt=\"license\" /\u003e\u003c/a\u003e\n\u003cimg src=\"https://img.shields.io/github/stars/middlewarehq/middleware?style=for-the-badge\" alt=\"Stars\" /\u003e\n\u003cimg referrerpolicy=\"no-referrer-when-downgrade\" src=\"https://static.scarf.sh/a.png?x-pxid=d3133c9b-3562-4048-863a-04bee8ad4818\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003ca href=\"https://mhq.link/oss-community\"\u003eJoin our Open Source Community\u003c/a\u003e\u003c/p\u003e\n\n![Middleware Opensource](https://github.com/middlewarehq/middleware/blob/main/media_files/banner.gif)\n\n\n## Introduction\n**Middleware** is an open-source tool designed to help engineering leaders measure and analyze the effectiveness of their teams using the [DORA metrics](https://dora.dev). The DORA metrics are a set of [four key values](https://dora.dev/guides/dora-metrics-four-keys/) that provide insights into software delivery performance and operational efficiency.\n\nThey are:\n- **Deployment Frequency**: The frequency of code deployments to production or an operational environment.\n- **Lead Time for Changes**: The time it takes for a commit to make it into production.\n- **Mean Time to Restore**: The time it takes to restore service after an incident or failure.\n- **Change Failure Rate**: The percentage of deployments that result in failures or require remediation.\n\n**Table of Contents**\n\n- [Middleware - Open Source](#introduction)\n  - [Features](#-features)\n  - [Quick Start](#-quick-start)\n    - [Installing Middleware](#-installing-middleware)\n    - [Troubleshooting](#%EF%B8%8F-troubleshooting)\n  - [Developer Setup](#-developer-setup)\n    - [Using Gitpod](#%EF%B8%8F-using-gitpod)\n    - [Using Docker](#-using-docker)\n    - [Manual Setup](#%EF%B8%8F-manual-setup)\n  - [Usage](#-usage)\n  - [How we Calculate DORA](#-how-we-calculate-dora-metrics)\n  - [Roadmap](#%EF%B8%8F-roadmap)\n  - [Contributing guidelines](#%EF%B8%8F-contributing-guidelines)\n  - [Developer Automations](#-developer-automations)\n  - [Security guidelines](#%EF%B8%8F-security-guidelines)\n  - [License](#license)\n\n## 🚀 Features\n\n- Integration with various CI/CD tools\n- Automated collection and analysis of DORA metrics\n- Visualization of key performance indicators\n- Customizable reports and dashboards\n- Integration with popular project management platforms\n\n## ✨ Quick Start\n\n### ⭐ Installing Middleware\n* Ensure that you have [docker](https://www.docker.com/products/docker-desktop/) installed and running.\n\n* Open the terminal and run the following command:\n\n  ```bash\n  docker volume create middleware_postgres_data\n  docker volume create middleware_keys\n  docker run --name middleware \\\n             -p 3333:3333 \\\n             -p 9696:9696 \\\n             -p 9697:9697 \\\n             -v middleware_postgres_data:/var/lib/postgresql/data \\\n             -v middleware_keys:/app/keys \\\n             -d middlewareeng/middleware:latest\n  docker logs -f middleware\n  ```\n\n- Wait for sometime for the services to be up.\n\n- The app shall be available on your host at http://localhost:3333.\n\n## 🛠️ Troubleshooting\n1. In case you want to stop the container, run the following command:\n\n   ```bash\n   docker stop middleware\n   ```\n\n2. In order to fetch latest version from remote and then starting the system, use following command:\n   ```bash\n   docker pull middlewareeng/middleware:latest\n   docker rm -f middleware || true\n   docker run --name middleware \\\n              -p 3333:3333 \\\n              -v middleware_postgres_data:/var/lib/postgresql/data \\\n              -v middleware_keys:/app/keys \\\n              -d middlewareeng/middleware:latest\n   docker logs -f middleware\n   ```\n\n3. If you see an error like: `Conflict. The container name \"/middleware\" is already in use by container`. \\\n   Then run following command before running the container again:\n   ```bash\n   docker rm -f middleware\n   ```\n\n4. If you wish to delete all the data saved in the container, you can delete the volumes created by running the following command:\n   ```bash\n   docker volume rm middleware_postgres_data middleware_keys\n   ```\n\n\n## 👩‍💻 Developer Setup\n\n### ☁️ Using GitPod\n\nGitpod enables development on remote machines and helps you get started with Middleware if your machine does not support running the project locally.\n\nIf you want to run the project locally you can [setup using docker](#-using-docker) or [setup everything manually](#-manual-setup).\n\n1. Click the button below to open this project in Gitpod.\n\n2. This will open a fully configured workspace in your browser with all the necessary dependencies already installed.\n\n[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/middlewarehq/middleware)\n\nAfter initialization, you can access the server at port 3333 of the gitpod instance.\n\n### 🐳 Using Docker\n\n\u003e [!IMPORTANT]\n\u003e We recommend minimum 16GB RAM when developing locally.\n\nIf you don't have docker installed, please install docker [over here](https://docs.docker.com/get-docker/).\nMake sure docker is running.\n\n1. **Clone the Repository**:\n\n   ```bash\n   git clone https://github.com/middlewarehq/middleware\n   ```\n\n2. **Navigate to the Project Directory**:\n\n   ```bash\n   cd middleware\n   ```\n\n3. **Run `dev.sh` script in the project root 🪄**\\\n    `./dev.sh` creates a `.env` file with required development environments and runs a CLI with does all the heavy lifting from tracking the container with `docker compose watch` to providing you with logs from different services.\\\n    The usage is as follows:\n   ```bash\n   ./local-setup.sh # Optional; See note\n   ./dev.sh\n   ```\n   You may update the `env.example` and set `ENVIRONMENT=prod` to run it in production setup.\\\n   Further if any changes are required to be made to ports, you may update the `docker-compose.yml` file, accordingly.\n\n   **Note** about `local-setup.sh`: While you don't need to run this script, it takes care of any local environment setup for automatic linting without which your PRs may fail the linter check.\n4. **Access the Application**:\n   Once the project is running, access the application through your web browser at http://localhost:3333.\n   Further, other services can be accessed at:\n    - The analytics server is available at http://localhost:9696.\n    - The sync server can be accessed at http://localhost:9697.\n    - The postgres database can be accessed at host: `localhost`, port: `5434`, username: `postgres`, password: `postgres`, db name: `mhq-oss`.\n    - The redis server can be accessed at host: `localhost`, port: `6385`.\n\n5. **View the logs**: Although the CLI tracks all logs, the logs of services running inside the container can be viewed in different terminals using the following commands:\n\n   **Frontend logs**\n   ```bash\n   docker exec -it middleware-dev tail --lines 500 -f /var/log/web-server/web-server.log\n   ```\n   **Backend api server logs**\n   ```bash\n   docker exec -it middleware-dev tail --lines 500 -f /var/log/apiserver/apiserver.log\n   ```\n   **Backend sync server logs**\n   ```bash\n   docker exec -it middleware-dev tail --lines 500 -f /var/log/sync_server/sync_server.log\n   ```\n   **Redis logs**\n   ```bash\n   docker exec -it middleware-dev tail --lines 500 -f /var/log/redis/redis.log\n   ```\n   **Postgres logs**\n   ```bash\n   docker exec -it middleware-dev tail --lines 500 -f /var/log/postgres/postgres.log\n   ```\n\n\n## 🛠️ Manual Setup\n\nTo set up middleware locally, follow these steps:\n\n1. **Clone the Repository**:\n\n   ```bash\n   git clone https://github.com/middlewarehq/middleware.git\n   ```\n\n2. **Navigate to the Project Directory**:\n\n   ```bash\n   cd middleware\n   ```\n\n3. **Run Redis and Postgres Containers**:\n\n    If you don't have docker installed, please install docker [over here](https://docs.docker.com/get-docker/)\n\n    Run the following commands to run Postgres and Redis using docker.\n\n     ```bash\n     cd database-docker \u0026\u0026 docker-compose up -d\n     ```\n\n    If you don't prefer Docker, you can choose to install [Postgres](https://www.postgresql.org/download/) and [Redis](https://redis.io/docs/latest/operate/oss_and_stack/install/install-redis/) manually.\n\n    Once you are done with using or developing Middleware, you can choose to close these running container. (NOTE: Don't do this if you are following this document and trying to run Middleware.)\n\n    ```bash\n    cd database-docker/\n    docker-compose down -v\n    ```\n\n4. **Generate Encryption keys**:\n\n    Generate encryption keys for the project by running the following command in the project root directory:\n\n    ```bash\n    cd setup_utils \u0026\u0026 . ./generate_config_ini.sh \u0026\u0026 cd ..\n    ```\n\n5. **Backend Server Setup**\n\n    - Install python version `3.11.6`\n\n      - For this you can install python from [over here](https://www.python.org/downloads/) if you don't have it on your machine.\n      - Install pyenev\n\n        ```bash\n        git clone https://github.com/pyenv/pyenv.git ~/.pyenv\n        ```\n\n      - Add pyenv to your shell's configuration file (.bashrc, .bash_profile, .zshrc, etc.):\n\n        ```bash\n        echo 'export PYENV_ROOT=\"$HOME/.pyenv\"' \u003e\u003e ~/.bashrc\n        echo 'export PATH=\"$PYENV_ROOT/bin:$PATH\"' \u003e\u003e ~/.bashrc\n        ```\n\n      - Reload your shell:\n        ```\n        source ~/.bashrc\n        ```\n    - Move backend directory to create a virtual environment\n\n      ```bash\n      cd backend\n      python -m venv venv\n      ```\n\n    - Activate virtual environment\n\n      ```bash\n      . venv/bin/activate\n        ```\n\n    - Install Dependencies\n\n      ```bash\n      pip install -r requirements.txt -r dev-requirements.txt\n      ```\n\n    - Create a `.env` file in the root directory and add the following environment variables, replacing the values with your own if needed:\n\n      ```text\n      DB_HOST=localhost\n      DB_NAME=mhq-oss\n      DB_PASS=postgres\n      DB_PORT=5434\n      DB_USER=postgres\n      REDIS_HOST=localhost\n      REDIS_PORT=6385\n      ANALYTICS_SERVER_PORT=9696\n      SYNC_SERVER_PORT=9697\n      PORT=3333\n      DEFAULT_SYNC_DAYS=31\n      ```\n\n    - Start the backend servers\n\n      - Change Directory to analytics_server\n        ```bash\n        cd analytics_server\n        ```\n\n      - For backend analytics server:\n        ```bash\n        flask --app app --debug run --port 9696\n        ```\n\n      - For backend sync server:\n        ```bash\n        flask --app sync_app --debug run --port 9697\n        ```\n        NOTE: Open this sync sever in a new terminal window after activating the virtual environment only after starting analytics server.\n\n6. **Web Server Setup**\n\n   - Install NodeJs 22.x either [manually](https://nodejs.org/en/download) or using a tool like [nvm](https://github.com/nvm-sh/nvm) or [volta](https://volta.sh/).\n\n   - Install `yarn` package manager\n     ```bash\n     npm install --global yarn\n     ```\n   - Change Directory to web-server and install packages\n     ```bash\n     cd web-server\n     yarn\n     ```\n\n   - Start the web-server\n     ```bash\n     yarn dev\n     ```\n\n7. **Access the Application**:\n   Once the project is running, access the application through your web browser at http://localhost:3333. \\\n   Additionally:\n   - The analytics server is available at http://localhost:9696.\n   - The sync server can be accessed at http://localhost:9697.\n\n\n# 🚀 Usage\n\n![Product Demo](https://github.com/middlewarehq/middleware/blob/main/media_files/product_demo_1.gif)\n\n- Setup the project by following the [steps mentioned above](#-quick-start).\n- Generate and Add your PAT token from code provider.\n- Create a team and select repositories for the team.\n- See Dora Metrics for your team.\n- Update settings related to incident filters, excluded pull requests, prod branches etc to get more accurate data.\n\n## 📖 How we Calculate Dora Metrics\n\nMiddleware can display DORA Metrics using exclusively Pull Requests based data. The aim is to provide Dora Metrics to anyone and everyone using their Git data, regardless of other integrations, in as few steps as possible.\n\nIn its totality, Dora Metrics are derived from Pull Requests, Deployments, and Incidents.\n\nTo learn more about how it's done, [look at our documentation here](https://middlewarehq.com/docs/product/oss/calculations).\n\n## 🛣️ Roadmap\n\nComing Soon!\n\n## ❤️ Contributing guidelines\n\n![contributor Metrics](https://open-source-assets.middlewarehq.com/svgs/middlewarehq-middleware-contributor-metrics-dark-widget-premium.svg)\n\nTo get started contributing to middleware check out our [CONTRIBUTING.md](https://github.com/middlewarehq/middleware/blob/main/CONTRIBUTING.md).\n\n\u003e [!IMPORTANT]\n\u003e ✨ We offer **SWAG** for solving issues labelled [`advanced`](https://github.com/middlewarehq/middleware/issues?q=is%3Aissue+is%3Aopen+label%3Aadvanced)! ✨\n\u003e _Please confirm with our team on respective issues before proceeding._\n\n\u003e [!IMPORTANT]\n\u003e 👩‍💻 When new hiring positions open, we look at our open source contributors first! 👨‍💻\n\u003e _[Join our Slack](https://mhq.link/oss-community) so we can reach out to you._\n\nWe appreciate your contributions and look forward to working together to make Middleware even better!\n\n## 👨‍💻 Developer Automations\n\nThis sections contains some automation scripts that can generate boilerplate code to extend certain features and ship faster 🚀\n\n### 1. Adding New Settings in Backend\n\n- Context: Initially, adding a new setting required context of the settings system, changes across some files and making adapters and defaults based on the new setting class structure.\n- This can now be done by running the `python make_new_setting.py` script in the `./backend/dev_scripts` directory\n\nIf you are in the root directory, you can run:\n```\npython ./backend/dev_scripts/make_new_setting.py\n```\n\n- Enter the setting name in the consitent format.\n- Add the required keys and their types. Enter `done` once you have added all the fields.\n- Update imports and linting.\n- You are good to go :tada\"\n- Note: For more non-primitive types in the setting such as uuid, enums etc, you will have to make changes to the generated adaptors.\n\n\nhttps://github.com/middlewarehq/middleware/assets/70485812/f0529fa7-a2cb-44b1-ae07-2a7c97f56bef\n\n# ⛓️ Security guidelines\n\nTo get started contributing to middleware check out our [SECURITY.md](https://github.com/middlewarehq/middleware/blob/main/SECURITY.md).\n\nWe look forward to your part in keeping Middleware secure!\n\n\n## License\n\nThis project is licensed under the [Apache 2.0](https://github.com/middlewarehq/middleware/blob/main/LICENSE) License - see the LICENSE.md file for details.\n\n\n\n![Banner](https://github.com/middlewarehq/middleware/blob/main/media_files/banner.png)\n","funding_links":[],"categories":["artificial-intelligence","TypeScript","\u003ca name=\"TypeScript\"\u003e\u003c/a\u003eTypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiddlewarehq%2Fmiddleware","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmiddlewarehq%2Fmiddleware","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiddlewarehq%2Fmiddleware/lists"}