Installing Midaz monorepo

Midaz uses Docker Compose to simplify setup and ensure consistency across development environments. This guide will walk you through the step-by-step installation of Midaz — now available as a monorepo that includes both the Ledger core and the Midaz Console, its visual interface for managing operations.

Whether you're an experienced developer or just getting started, you'll find clear and practical instructions to get everything running smoothly on your machine.

Have you already installed Midaz and the Midaz Console from separate repositories?

If so, we recommend discontinuing that setup, as the standalone Console repository has been deprecated. From now on, all new developments will be available exclusively in the unified Midaz monorepo.

To keep your system up to date, expand the section below and follow the instructions provided.

make up

cd midaz/components/console

npm install

npm run set-local-env

npm run dev

New to Midaz? Here's everything you need to install the monorepo

1. System Requirements

Your computer must meet the following minimum requirements:

• Operating System:
  • Windows: Windows 10 version 2004 or later (Build 19041 or newer)
  • macOS: Current or two most recent versions
  • Linux: Ubuntu or Debian recommended
• RAM: Minimum of 8 GB to run Docker
• Disk Space: At least 20 GB free
• Internet: Stable connection to download tools and dependencies
• Browser: Google Chrome, Firefox, or any modern browser

2. Required Tools

• Docker Desktop: Installation Guide
• Git: Installation Guide
• Postman (optional, for testing APIs): Download POSTMAN
• Package Manager:
  • macOS: Homebrew
  • Linux (native or via WSL): Use your system’s built-in package manager (e.g., apt, dnf, yum)

3. (Windows only) Install WSL

Midaz works best in a Linux environment. If you’re using Windows, follow these steps to install WSL (Windows Subsystem for Linux):

1. Press Win + R, type powershell, then right-click and select run as administrator.
2. Run the following command:

wsl --install

👍

Tip

After installation, you can open WSL by searching for "Ubuntu" in the Start Menu.

4. Restart your computer if prompted.

Installing the Midaz monorepo

Step 1 – Open your terminal

• macOS/Linux: Use the Terminal.
• Windows: Open the Ubuntu app (WSL).

🚧

Important

If you’re using Windows, run all the following commands inside the Ubuntu terminal.

If you're not familiar with the terminal, check out our Command line basics guide.

Step 2 – Install the make command

Midaz uses make to automate setup. Install it according to your operating system:

• Linux (native or WSL - Ubuntu/Debian):

sudo apt install make

• macOS:

brew install make

Step 3 – Download the Midaz code (monorepo)

1. Navigate to the directory where you want to save the project. For example, to save it to your Desktop:

cd ~/Desktop

2. Clone the repository:

git clone https://github.com/LerianStudio/midaz.git

3. Enter the project folder:

cd midaz

Step 4 – Set up environment variables

Run the command below to configure the .env files:

make set-env

Step 5 – Start the services

Ensure Docker is running and execute:

make up

This command will launch all Midaz services — including the Console — using Docker.

From now on, every time you start Docker, the Console will launch automatically alongside Midaz.

Step 6 – Access your local environment

With everything up and running, open your browser and visit:

• Onboarding APIs: http://localhost:3000
• Transaction APIs: http://localhost:3001
• Midaz Console: http://localhost:8081

🚧

Important

To access the Console, make sure the environment variables are set and Docker is running.

Develop within the Midaz Console

If you plan to actively develop within the Midaz Console, running it via Docker is not ideal, as the containerized environment makes live editing more difficult.

Instead, we recommend stopping the Console container to prevent port conflicts—since Docker binds the Console to port 8081 by default.

Here’s how to proceed:

1. To stop the Console container, run:

docker stop midaz-console

2. From the midaz root directory, navigate to the Console folder:

cd components/console

3. Install dependencies (if you haven’t already):

npm install

4. Set up your local environment:

npm run set-local-env

5. Start in development mode:

npm run dev

This may take a few minutes on the first run — wait for the initial loading to complete.

📘

Note

If this is your first time running the Midaz Console, the loading process of the pages might take a bit longer. This is expected as data is being compiled and displayed.

Authentication

Starting from Midaz v1.49, authentication is not required in the Community version — you can access the APIs directly.

📘

Note

Want authentication features? Use the Access Manager plugin (Enterprise only).

For more info, contact our team.

Next step

• Navigate to midaz/postman
• Import MIDAZ.postman_collection.json into Postman
• Explore the available endpoints!

👍

Tip

Ready to build? Follow our Quick Start Guide to create your first Midaz structure.

Community, support & contribution

Need help, want to contribute, or just follow what’s new?

• Join our community on Discord
• Start discussions and report bugs on GitHub
• Follow us on Twitter for the latest updates

Ready to contribute? Read our Contributing Guide and pick an issue to get started.

👍

Need expert help?

Our consulting team can support you in building or optimizing your Midaz structure.

Contact us for more information.

License

Midaz is an open-source project licensed under the Apache 2.0 License.