Midaz uses Docker Compose to simplify setup and ensure consistency across development environments. This guide walks you through installing Midaz, now available as a unified monorepo that includes both the Ledger and the Midaz Console—the 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.

System Requirements

• Operating System:

  • Windows: Windows 10 version 2004 or later (Build 19041+)
  • macOS: Current or previous two versions
  • Linux: Ubuntu or Debian recommended

• RAM: At least 8 GB

• Disk Space: 20 GB free

• Internet: Stable connection

• Browser: Chrome, Firefox, or equivalent

Required Tools

• Docker Desktop

• Git

• Postman (optional)

• Package Manager:

  • macOS: Homebrew
  • Linux: Use your system’s package manager (e.g., apt, dnf)
  
  

Authentication

The community version of Midaz has no built-in authentication. APIs are publicly accessible.

If you need authentication, use the Access Manager plugin (Enterprise only).

Contact our team to learn more.

❗️

Important

Without authentication, we strongly recommend keeping Midaz on a secure private network.

Already using separate repositories?

If you’ve installed Midaz and the Console from separate repositories, we recommend migrating to the monorepo setup. The standalone Console repo has been deprecated, and all future development will happen in the unified structure.

❗️

Important

The standalone Console repository is no longer maintained. To stay up to date, switch to the unified monorepo.

make up

cd midaz/components/console
npm install
npm run set-local-env
npm run dev

Windows Setup: Install WSL

If you are using Windows, you must install WSL (Windows Subsystem for Linux) and run Midaz via it.

1. Open PowerShell as an administrator.

2. Run:

   Bash

   wsl --install

3. Restart if prompted.

👍

Tip

After installing WSL, open Ubuntu via the Start Menu.

Install Midaz (Monorepo)

Step 1 – Open your terminal

• macOS/Linux: Terminal
• Windows: Ubuntu (WSL)

❗️

Important

If using Windows, run all commands inside Ubuntu (WSL). Not familiar with terminals? Check out this beginner guide.

Step 2 – Install make

• Linux:

  Bash

  sudo apt install make

• macOS:

  Bash

  brew install make

Step 3 – Download the Midaz monorepo

1. Choose your working directory:

   Bash

   cd ~/Desktop

2. Clone the repo:

   Bash

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

3. Enter the folder:

   Bash

   cd midaz

Step 4 – Set up environment variables

make set-env

Step 5 – Start the services

Make sure Docker is running, then:

make up

All services, including the Console, will launch.

Step 6 – Access your environment

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

❗️

Important

Make sure environment variables are set and Docker is up before accessing the Console.

Developing the Console locally

If you plan to develop the Console actively, Docker is not ideal. Run it locally to avoid port binding issues. To do so, follow these steps:

1. Stop the Console container.

   Bash

   docker stop midaz-console

2. Go to the Console folder.

   Bash

   cd components/console

3. Install dependencies.

   Bash

   npm install

4. Set environment.

   Bash

   npm run set-local-env

5. Start dev mode.

   Bash

   npm run dev

📘

Note

The first load may take a few minutes as pages are compiled.

Try the API

• Go to midaz/postman
• Import MIDAZ.postman_collection.json into Postman
• Explore available endpoints

👍

Tip

Ready to build? Start with our Quick Start Guide.

Community, Support & Contribution

• Join us on Discord
• Report issues on GitHub
• Follow @LerianStudio on Twitter

Ready to contribute? See our Contributing Guide.

👍

Tip

Need expert help? Talk to our team for hands-on support.

License

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