Midaz is an open-source ledger designed to be easy to run, extend, and test locally. You can install it with just a few commands using Docker Compose, which sets up the full environment (backend APIs and Midaz Console) in one go.

Whether you’re building something new or exploring how Midaz works under the hood, this guide walks you through the full setup process.

📘

Note

Midaz is now distributed as a single repository. No need to install the Ledger and Console separately.

System requirements

Tools you’ll need

• Docker Desktop

• Git

• Postman (optional)

• Package Manager:

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

On Windows? Install WSL

If you're using Windows, you must install WSL (Windows Subsystem for Linux) to run Midaz.

1. Open PowerShell as an administrator.

2. Run:

   Text

   wsl --install

3. Restart your machine if needed.

4. Once installed, open the Ubuntu app from the Start Menu to continue the setup.

Install Midaz

Step 1 – Open your terminal

• macOS/Linux: Use your Terminal app.
• Windows: Open Ubuntu via 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:

  Text

  sudo apt install make

• macOS:

  Text

  brew install make

Step 3 – Download the Midaz repo

1. Choose your working directory:

   Text

   cd ~/Desktop

2. Clone the repo:

   Text

   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 Docker is up and all .env files are properly set before opening the Console.

Running the Console in dev mode

If you’re actively developing the Console, we recommend running it outside Docker to avoid conflicts and improve speed.

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 build might take a minute as pages are compiled.

Try the API

Want to explore the Midaz APIs?

1. Go to midaz/postman.
2. Import MIDAZ.postman_collection.json into Postman.
3. Explore available endpoints.

👍

Tip

Ready to build? Start with our Quick Start Guide.

Authentication

By default, the community version of Midaz is open and does not require authentication. This makes local testing easier.

If you need authentication, use the Access Manager plugin, available for enterprise customers.

❗️

Important

Without authentication, we recommend running Midaz in a secured, private environment only.

Community and contribution

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

Want to contribute? Start with 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.