​
Prerequisites

Make sure you have the following ready:

​
1. System requirements

Your computer should meet these minimum requirements:
  • Operating System:
    • Windows: Windows 10 version 2004 or later (Build 19041 and higher).
    • macOS: Current or the two most recent versions.
    • Linux: Ubuntu or Debian are preferred.
  • Memory (RAM): At least 8 GB is recommended for running Docker.
  • Disk Space: 20 GB of free storage.
  • Internet: A stable connection to download tools and dependencies.
  • Browser: Google Chrome, Firefox, or any modern browser

​
2. Tools you need

First time using Node.js or npm?No problem, we’ve got you covered. If you’re new to these tools or not sure how to install them, check out our Beginner-Friendly Guide to Node.js and npm. It walks you through everything step by step.

​
3. Install the make command

Midaz uses make to automate the setup. Install it using one of the following options, depending on your OS:
  • Linux (Ubuntu/Debian) - open Terminal and run:
sudo apt install make
  • macOS - open Terminal and run:
brew install make
  • Windows - open PowerShell as Administrator and run:
choco install make

​
4. (Windows only) Install WSL

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

​
Install WSL

1

Press Win + R, type powershell, and right-click to run as Administrator.
2

Run the following command:
wsl --install
3

Restart your computer if prompted.
This installs Ubuntu by default. After restart, you’ll be asked to create a username and password; choose anything you like (this won’t affect Windows). For more information about WSL, refer to Microsoft’s official documentation.
TipYou only need to do this once. Next time, just search for Ubuntu in the Start Menu to open WSL.

​
Setting up Midaz All-in-One Suite

This is the easiest way to get the full Midaz experience running on your computer. Whether you’re testing things out or starting development, the steps below will walk you through everything — no deep technical knowledge required.

​
Step 1 - Open your terminal

You’ll need to use a terminal to run a few commands.
  • On macOS or Linux, you can open the Terminal app.
  • On Windows, open the Ubuntu app (WSL) if you’ve set it up.
TipNot sure how to open your terminal? Check out the Command Line Basics guide.

​
Step 2 - Download Midaz All-in-One Suite

This step copies the Midaz code from GitHub to your computer. To do so, run this command: 
git clone --recurse-submodules git@github.com:LerianStudio/midaz-stack.git
You’ll now have a folder called midaz-stack with everything you need.

​
Step 3 - Move into the Midaz folder

Now let’s move into that folder so you can work with it: 
cd midaz-stack
You’re now inside the Midaz project directory and ready to launch the suite.

​
Step 4 - Start the Midaz Suite

Before running this command:
  • Make sure Docker is running on your machine.
  • If you’re using Windows, make sure you’re inside WSL (Windows Subsystem for Linux).
Run this command to start everything at once: 
make up
This will launch all Midaz services, including the APIs and Console. The first time might take a little longer as everything sets up.

​
Step 5 - Open Midaz in your browser

Once the services are up and running, you can visit them in your browser:
ImportantThese links only work while the Midaz Suite is running in your terminal.
Want to explore the Midaz APIs?Head over to our API Reference to start testing endpoints and learning what they do.

​
Authentication

Starting from Midaz v1.49, authentication is no longer required in the Community version. You can make requests to the Midaz APIs directly. Soon, you will be able to use our Auth & Identity plugin to add the authentication features to your environment. For more information, contact a Sales Representative.
Older versionsIf you are using an older version of Midaz, access our authentication documentation.

​
Additional commands

You can also use the following commands:
  • Start the services: make start
  • Stop the services: make stop or make down
  • Restart the services: make restart
  • Rebuild and restart: make rebuild-up
  • Build all services: make build
  • Clean up all resources: make clean
  • Show help: make help (for all available commands)
  • Show Midaz commands: make midaz-help
  • Show Console commands: make midaz-console-help

​
Development commands

For development purposes, you can run specific commands for each component:

​
Run a Midaz command

Use the following command to run commands that are specific to Midaz Core: 
cd midaz && make <command>

​
Run a Midaz Console command

Use the following command to run commands that are specific to Midaz Core: 
cd midaz-console && npm run <command>

​
Next Steps

Once your setup is complete, you can:
  1. Explore APIs: Use the Postman collection in the postman folder of your repository or download it here.
  2. Build Your First Structure: Check out the Quick Start Guide to create your first Midaz Structure.

​
Need Help?

If you have questions or encounter issues, we’re here to help:
  • Contribution guidelines: Learn how to contribute to the Midaz project here.
  • Join the community: Connect with us on Discord.
  • Open issues: Find beginner-friendly issues to contribute to or propose your own.
Together, let’s build the future of ledger management!