DEV Community

Midnight Aliit Fellowship profile image Gutopro
Gutopro for Midnight Aliit Fellowship

Posted on

Building on Midnight with Windows — A Real Developer's WSL2 Setup Guide

#blockchain #midnightchallenge #aliit #web3

Midnight Network Challenge: Enhance the Ecosystem

midnight
If you're on Windows and you want to build on Midnight, the first thing you need to know is that Midnight's toolchain — the Compact compiler, proof server, and the rest — are Linux binaries. They won't run natively on Windows. Full stop.

That doesn't mean you're locked out. Windows has a feature called WSL2 — Windows Subsystem for Linux — that gives you a real Linux environment running inside Windows. Once it's set up you get a proper Ubuntu terminal, access to all the Linux dev tools you need, and a stable foundation for Midnight development.

I set up my entire Midnight development environment on WSL2. This guide documents exactly what I did — including the parts that aren't obvious and the parts that caught me off guard.

Step 1: Enable WSL2

Microsoft has official documentation for enabling WSL2. Follow that guide to get WSL installed on your machine before continuing here.

👉 Enable WSL2 on Windows — Official Microsoft Guide

Come back here once WSL is enabled and you have Ubuntu running.

Step 2: Download Ubuntu from the Microsoft Store

Open the Microsoft Store and search for Ubuntu. Select Ubuntu 24.04 LTS and click Get.

Once it installs, launch it from the Start menu. The first launch will ask you to create a Linux username and password.

Note:
When you type your password nothing shows on screen. That's intentional — Linux hides password input by default. Just type it and press Enter.

Verify WSL2 is active by opening PowerShell and running:

# Windows PowerShell
wsl --list --verbose
Enter fullscreen mode Exit fullscreen mode

You should see Ubuntu listed with Version 2. If it shows Version 1, set WSL2 as the default with:

# Windows PowerShell
wsl --set-default-version 2
Enter fullscreen mode Exit fullscreen mode

Step 3: Configure WSL2 Memory — Don't Skip This

This is the step I wish someone had told me about before I started.

By default WSL2 only gets 1GB of memory. The Midnight proof server needs at least 4GB to generate ZK proofs without crashing. If you skip this configuration your proof server will run but fail silently or crash mid-proof with no obvious error message. I learned this the hard way.

Create a .wslconfig file in your Windows user directory. Open PowerShell and run:

# Windows PowerShell
notepad "$env:USERPROFILE\.wslconfig"
Enter fullscreen mode Exit fullscreen mode

Add this configuration:

# .wslconfig
[wsl2]
memory=8GB
processors=4
swap=3GB
localhostForwarding=true
Enter fullscreen mode Exit fullscreen mode

If your machine has less than 16GB RAM adjust accordingly. The minimum that works reliably for Midnight development is memory=4GB.

Setting Minimum Recommended
memory 4GB 8GB
processors 2 4
swap 1GB 3GB
localhostForwarding true true

Save the file then restart WSL:

# Windows PowerShell
wsl --shutdown
Enter fullscreen mode Exit fullscreen mode

Reopen Ubuntu from the Start menu.

Step 4: Install curl

Start with the fundamentals. curl is needed to download everything else.

# WSL Ubuntu terminal
sudo apt update
sudo apt install -y curl
Enter fullscreen mode Exit fullscreen mode

Step 5: Install Git

You'll need git for version control and cloning repositories.

# WSL Ubuntu terminal
sudo apt install -y git
Enter fullscreen mode Exit fullscreen mode

Step 6: Install Node.js 22

Midnight requires Node.js 22 or higher. Install it using nvm — don't use a Windows-native Node.js installation, as version conflicts will cause problems down the line.

# WSL Ubuntu terminal
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
node --version
Enter fullscreen mode Exit fullscreen mode

Note:
zsh users: Replace ~/.bashrc with ~/.zshrc in the commands above.

Note:
Why pin to 22? create-mn-app and the Midnight SDK have been validated against Node.js 22. Using a newer major version may work, but you could encounter unexpected compatibility issues. Check the Midnight documentation for the latest supported range

Note:
nvm version: The installer URL above pins nvm to v0.40.3. Check the nvm releases page before running to confirm it's still the latest stable version and update the URL if needed.

Verify the installation before moving on:

node --version   # should print v22.x.x
npm --version
Enter fullscreen mode Exit fullscreen mode

Step 7: Install Docker Engine

The Midnight proof server runs as a Docker container. You need Docker Engine installed inside WSL — not Docker Desktop.

Set up Docker's apt repository:

# WSL Ubuntu terminal
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
Enter fullscreen mode Exit fullscreen mode

Install Docker packages:

# WSL Ubuntu terminal
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Enter fullscreen mode Exit fullscreen mode

Add your user to the docker group so you can run Docker without sudo:

# WSL Ubuntu terminal
sudo usermod -aG docker $USER
newgrp docker
Enter fullscreen mode Exit fullscreen mode

Start the Docker daemon:

# WSL Ubuntu terminal
sudo service docker start
Enter fullscreen mode Exit fullscreen mode

Verify Docker works:

# WSL Ubuntu terminal
docker run hello-world
Enter fullscreen mode Exit fullscreen mode

Step 8: Install the Compact Toolchain 

# WSL Ubuntu terminal
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/midnightntwrk/compact/releases/latest/download/compact-installer.sh | sh
Enter fullscreen mode Exit fullscreen mode

Add to PATH:

# WSL Ubuntu terminal
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Enter fullscreen mode Exit fullscreen mode

Note:
zsh users: Replace ~/.bashrc with ~/.zshrc.

Verify:

# WSL Ubuntu terminal
compact --version
Enter fullscreen mode Exit fullscreen mode

Step 9: Scaffold Your Project with create-mn-app

This is where things get streamlined. The Midnight team ships create-mn-app — a scaffolding tool that sets up your entire project structure including wallet scripts, contract source, compilation config, and deployment tooling.

# WSL Ubuntu terminal
npx create-mn-app my-app
cd my-app
npm run setup
Enter fullscreen mode Exit fullscreen mode

npm run setup will:

  • Compile your Compact smart contract
  • Check your Node.js, Docker, and Compact compiler versions for compatibility
  • Start the proof server via Docker Compose
  • Guide you interactively through wallet creation or restoration

Wallet creation is interactive. When npm run deploy runs as part of setup, it will prompt you to either create a new wallet or restore from an existing seed. If you're starting fresh, choose option 1. Your seed will be saved to .midnight-seed (chmod 600) — back it up and never commit this file.

Note:
Version mismatch: create-mn-app checks that your @midnight-ntwrk/compact-runtime version in package.json matches your installed compiler version. A mismatch causes a CompactError on compilation. If setup flags it, let it fix it automatically.

Once setup completes, your wallet address is printed to the terminal. Copy it and head to the faucet to get tNight tokens.

If you want a more complete starting point, the Counter DApp template gives you a real increment/decrement contract with ZK proofs already wired up:

# WSL Ubuntu terminal
npx create-mn-app my-app --template counter
cd my-app
npm run setup
Enter fullscreen mode Exit fullscreen mode

Step 10: Get tNight from the Faucet

Every transaction on Midnight costs DUST as gas — and DUST is generated automatically once your wallet holds tNight. Your wallet address was printed during npm run setup.

  1. Visit the preprod faucet
  2. Paste your wallet address
  3. Request tokens and wait ~2–5 minutes

Note:
Important: Always verify your wallet is configured for the preprod network before copying your address. The preprod faucet only recognizes addresses registered on preprod — submitting an address from a differently-configured wallet will return an invalid address error.

Note:
DUST balance: DUST accumulates over time based on the tNight in your wallet. If you attempt deployment immediately after funding and see a "Not enough DUST" error, wait a few minutes and retry with npm run deploy.

What Doesn't Work

Save yourself the debugging time — these approaches don't work:

Approach Why it fails
Running Compact compiler in PowerShell or CMD Linux binary — requires WSL
Running proof server natively on Windows Linux binary — requires WSL
Using Windows-native Node.js for Midnight projects Version and path conflicts
Keeping projects in /mnt/c/ Severely degraded file I/O performance
Submitting a mainnet-configured wallet address to preprod faucet Address not registered on preprod

Troubleshooting

Proof server crashes or produces no output — Almost always a memory issue. Increase memory in .wslconfig to at least 4GB, run wsl --shutdown, restart WSL.

Docker not found — Run sudo service docker start. If that fails, verify Docker is installed with docker --version.

compact not found — Add export PATH="$HOME/.local/bin:$PATH" to ~/.bashrc and run source ~/.bashrc.

Port 6300 not accessible — Add localhostForwarding=true to .wslconfig and restart WSL with wsl --shutdown.

Slow file operations — Move your project out of /mnt/c/ into your Linux home directory at ~/. The performance difference is significant.

CompactError: Version mismatch — Your compiler version and compact-runtime npm package version don't match. create-mn-app will flag this during setup and offer to fix it. If you hit it mid-project, update package.json to the matching runtime version and run npm install.

"Not enough DUST" during deployment — Your wallet is new and DUST hasn't accumulated yet. Wait a few minutes and run npm run deploy again. The deploy script retries automatically up to 8 times with a delay between attempts.

Next Steps

Your environment is ready. Run create-mn-app and let it scaffold your first project. The hello-world template compiles and deploys in minutes. Watch your transaction appear on chain in 1AM Explorer — that's your proof it's working.

If you hit issues not covered here, find me in the Midnight Discord as Guto — I've been through most of them already.

Top comments (0)