Hypermedia Build + Develop Setup

Building on Unix-Like Systems

The dev setup uses by using the Nix Package Manager, and Direnv. These tools auto-configure your environment so you don't have to manually install the required tools.


You must have the C toolchain installed globally on your machine. It can be gcc or clang with their corresponding linkers.

Install Nix

Nix is a package manger for Unix-like systems, which is very strict about isolating packages. It will not mess around with your existing system packages. Ideally Nix would be the only piece of software needed to build Mintter, but unfortunately some OpenGL packages, and some system libraries don't work quite well. We still leverage Nix to manage other tools and runtimes required to work with Mintter.
Install Nix by following the official documentation for your system. Follow the installation instructions precisely. To successfully complete the setup, you should write some information in your shell profile in order for Nix to work. It may be that the installer is able to do this setup for you, though.
NOTE: for macOS it may be necessary to create a virtual APFS volume, because Nix expects having access to /nix directory, but macOS in recent versions doesn't allow creating directories in the root catalog. The installer should guide you through the process. For Apple Silicon machines, it may be needed to install Rosetta.
To verify the installation, open an empty terminal window and run:
nix-env -i hello
This should run the GNU Hello program installed with Nix.

Install Direnv

Direnv is used to configure the development environment when you open up the project directory. It's useful because it makes configuration portable between developers, and won't pollute your global environment.
You can install Direnv with Nix:
nix-env -i direnv
IMPORTANT: To complete the setup you must add direnv shell hooks to your shell profile:
eval "$(direnv hook bash)"  # for bash
eval "$(direnv hook zsh)"   # for zsh
eval (direnv hook fish)     # for fish
Make sure to add the direnv hook after Nix configuration in the shell profile.
It's highly recommended to configure your IDE to work with direnv. We have setup the corresponding extension recommendations for VS Code.

Install System Libraries (non-nixOS Linux Only)

The setup for Linux is a bit more involved because some OpenGL libraries don't work well with Nix on non-nixOS distros.
So to compile on Linux you must have the following libraries installed:

Run Desktop Build

Build the app with the following command
./dev build-desktop
As it completes it will print the location of the built app

Building on Windows

Internally, none of us uses Windows for development, but we do build for Windows on Windows machines in CI. You can inspect the corresponding GitHub Actions workflow definitions to find out what needs to be installed to compile the project.

Dev: Run Desktop App

To run the app, by default it will run on the test network:
./dev run-desktop
You can also run against the production network:
MINTTER_P2P_TESTNET_NAME="" ./dev run-desktop

Build Web Site

You can build docker images for different modules of the system.
docker build -t mintterd . -f ./backend/cmd/mintterd/Dockerfile
docker build -t gateway . -f ./frontend/gateway/Dockerfile

Dev: Run Site

First cd into the project directory.
Start the daemon go daemon:
go run ./backend/cmd/mintter-site -data-dir=~/.mttsite -p2p.port=59000 --http.port=59001 -p2p.no-relay -grpc.port=59002
Then simultaneously run the Nextjs frontend:
HM_BASE_URL="http://localhost:3000" GRPC_HOST="http://localhost:59001" PORT=3000 yarn site
Now you can access the site at http://localhost:3000

Dev: Run Gateway

The gateway is a special configuration of the site that will serve any content from the p2p network.
First run the daemon:
MINTTER_P2P_TESTNET_NAME="dev" go run ./backend/cmd/mintter-site -data-dir=~/.mttgateway -p2p.port=57000  -grpc.port=57002 -http.port=57001 -p2p.no-relay -syncing.allow-push -syncing.no-discovery=false "http://localhost:3300"
Simultaneously run the Nextjs frontend:
NEXT_PUBLIC_ENABLE_GATEWAY=true NEXT_PUBLIC_GRPC_HOST="http://localhost:57001/" GRPC_HOST="http://localhost:57001/" PORT=3300 GW_NEXT_HOST="http://localhost:3300" yarn site
Now you can access the gateway at http://localhost:3300

Debug Details

We are developing various utilities to help you access the internals of the system for troubleshooting

Access JSON-CBOR Blobs

Use this URL: