Guides

Installing Midaz

Suggest Edits

Midaz uses Docker Compose to simplify setup and ensure consistency. This guide helps you install and run the Midaz Ledger on your computer, whether you’re a seasoned developer or completely new to this.

We’ll guide you through every step with clear, practical instructions.


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


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
  1. 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.

👍

Tip

You only need to do this once. Next time, just search for Ubuntu in the Start Menu to open WSL.


Setting Up Midaz

Follow these steps to set up and run the Midaz stack:

Step 1 – Open Your Terminal

  • On macOS or Linux, open the Terminal from your applications.
  • On Windows, open the Ubuntu app (WSL) from the Start menu.

❗️

Important

If you're using Windows, run all remaining commands inside the Ubuntu terminal.


Step 2 - Download the Midaz code

First, you’ll download a copy of Midaz to your computer.

  1. Open your terminal or command prompt.
  2. Navigate to the folder where you want to keep the project. For example, if you want to save it to your Desktop, you can run:
    1. On Windows, it might look like cd %USERPROFILE%\Desktop.
cd ~/Desktop
  1. Download the repository by running the following command:
    1. This will create a folder called midaz and place all the Midaz files inside it.
git clone https://github.com/LerianStudio/midaz.git
  1. Navigate to the midaz folder to continue the setup from there. To do so, run the following command:
cd midaz

👍

Tip

If you're unsure how to use the terminal, refer to the Command Line Basics guide.


Step 3 – Set Up Environment Variables

This command sets up important configuration files for Midaz:

  • You’ll only need to do this once.
make set-env

Step 4 – Start the Midaz Services

Make sure Docker is running (open Docker Desktop). Then run: 

make up

This launches the Midaz stack, a group of services working together behind the scenes.


Step 5 – Access Your Local Midaz Environment

Once everything is running, open your browser and go to these links:

This ensures you can seamlessly validate your setup and start interacting with the APIs right away. If any port conflicts occur, adjust them in your configuration files accordingly.

👍

API Reference

To learn more about our APIs, refer to our API Reference documentation.


Next: Install Midaz Console

Midaz Console is part of the Midaz environment and is available to all users. To install it, follow the steps in the Installing Midaz Console page.


Optional Commands

Want to go further? Here are some advanced commands:

  • Run tests: make test
  • Format code: make format
  • Run linter: make lint
  • Set up git hooks: make setup-git-hooks
  • Show help: make help (for all possible project management commands)

Next Steps

Once your Midaz project is set up, you can start using our APIs. To make this easier, we’ve made our API collection available on Postman. Here’s how to get started:

  1. Navigate to the folder where you cloned the Midaz repository. The .json file for the Postman collection is located in the midaz\postman folder.

    • Alternatively, you can download the collection directly from GitHub.

  2. Import the collection file into Postman. For guidance, refer to the Postman documentation.

  3. You’re all set to start exploring our endpoints.

👍

Ready to Build Your Midaz Structure?

Follow our Quick Start Guide to create your first Midaz Structure.


Authentication

Starting from Midaz v1.49, authentication is no longer required in the Community version. You can make requests to the Midaz APIs directly.

If you want to add the authentication features to your environment, you can do so by using the Access Manager plugin (available only for Enterprise clients). For more information, contact a Sales Representative.

📘

Older versions

If you are using an older version of Midaz, access our authentication documentation.


Need Help?

If you encounter any issues or want to get involved with the Midaz project, here are some resources:

  1. Contribution Guidelines: Read our Contribution Guidelines to learn how to contribute effectively.
  2. Join the Discussion: Connect with the community through our Discord channel. Discuss issues, share ideas, and learn from others.
  3. Pick an Issue: Start contributing by selecting an open issue labeled for beginners or propose your own.

Don't hesitate to take the first step, whether new to open-source or an experienced contributor. For more detailed information, consult our Guides or reach out through our community support channels.

👍

Need help creating your Midaz Setup?

Our consulting service can help you design your Midaz structure to fit your organization’s unique needs. Whether you’re starting from scratch or optimizing an existing setup, we’re here to guide you. For more information, contact us .

Updated 1 day ago