Whether you’re an experienced developer or just getting started, you’ll find clear and practical instructions to get everything running smoothly.
ImportantThis is the documentation for a deprecated version of Midaz. While it’s still operational and receives critical security updates, it’s no longer actively maintained or improved.For the best experience and ongoing support, switch to the newest version.

​
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](https:(.docker.com/get-docker/)
  • 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.
ImportantWithout 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.
ImportantThe standalone Console repository is no longer maintained. To stay up to date, switch to the unified monorepo.
1

Open your terminal and go to the midaz directory.
2

Pull the latest version of the repository.Option 1 – Run the Console via Docker (recommended)
make up
Then go to http://localhost:8081 in your browser.Option 2 – Run the Console manually using Node.js
cd midaz/components/console
npm install
npm run set-local-env
npm run dev
Access the Console at: http://localhost:8081
To run the Console manually, make sure only Midaz is running in Docker. Stop the Console container to avoid port conflicts.

​
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

wsl --install
3

Restart if prompted

Restart if prompted.
TipAfter installing WSL, open Ubuntu via the Start Menu.

​
Install Midaz (Monorepo)

​
Step 1 – Open your terminal

  • macOS/Linux: Terminal
  • Windows: Ubuntu (WSL)
ImportantIf using Windows, run all commands inside Ubuntu (WSL). Not familiar with terminals? Check out this beginner guide.

​
Step 2 – Install make

  • Linux: 
    sudo apt install make
  • macOS: 
    brew install make

​
Step 3 – Download the Midaz monorepo

1

Choose your working directory

cd ~/Desktop
2

Clone the repo

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

Enter the folder

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

ImportantMake 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

docker stop midaz-console
2

Go to the Console folder

cd components/console
3

Install dependencies

npm install
4

Set environment

npm run set-local-env
5

Start dev mode

npm run dev
NoteThe 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
TipReady to build? Start with our Quick Start Guide.

​
Community, Support & Contribution

Ready to contribute? See our Contributing Guide.
TipNeed expert help? Talk to our team for hands-on support.

​
License

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