DEV Community

Tosh
Tosh

Posted on

Midnight Development on Windows via WSL2: The Complete Setup Guide

#midnight #blockchain #typescript #web3

Midnight Development on Windows via WSL2: The Complete Setup Guide

When Midnight's documentation says "Linux and macOS," Windows developers have two choices: dual-boot, or use WSL2. WSL2 is the better option — you keep your Windows tooling, you get a real Linux kernel, and Docker integration works well. But the setup path has several undocumented gotchas that will eat your afternoon if you don't know about them.

This guide covers the complete path from a fresh Windows 11 machine to a running Midnight development environment. Every command is labeled with whether it runs in a Windows terminal or a WSL terminal. None of the "it works on my machine" hand-waving — this is the path that actually works.

What Does NOT Work

Before the setup steps, let's be explicit about what you cannot do on Windows. This will save you from going down dead ends.

Windows-native PowerShell: You cannot run the Midnight toolchain natively on Windows. The Compact compiler is a Linux binary. The proof server is a Linux binary. There is no Windows build of either. PowerShell commands for Midnight development do not exist.

Windows-native npm / Node.js: Installing Node.js with the Windows installer and running npm install from PowerShell will not work for Midnight development. Even if the packages install, the compiled binaries inside them target Linux. Keep your Windows Node.js installation if you use it for other things, but the Midnight toolchain needs a Node.js installation inside WSL.

Native Docker Desktop containers without WSL2 backend: Docker Desktop can run containers using either Hyper-V or WSL2 as the backend. The WSL2 backend is required for the Midnight local Docker stack to function correctly from inside WSL.

Everything from this point forward assumes you are working inside a WSL Ubuntu terminal unless explicitly stated otherwise.

Step 1: Install WSL2

Windows terminal (PowerShell or CMD, run as Administrator)

wsl --install
Enter fullscreen mode Exit fullscreen mode

This single command installs WSL2 with Ubuntu as the default distribution. It also enables the required Windows features (Virtual Machine Platform and Windows Subsystem for Linux).

Restart when prompted. After the restart, Ubuntu will complete its setup and ask you to create a UNIX username and password. Use something simple — this password is what sudo will ask for inside WSL.

Verify your installation:

wsl --list --verbose
Enter fullscreen mode Exit fullscreen mode

You should see Ubuntu listed with WSL version 2. If it shows version 1, run:

wsl --set-version Ubuntu 2
Enter fullscreen mode Exit fullscreen mode

Step 2: Configure Memory for the Proof Server

Windows terminal (Notepad or any text editor)

This is the step most tutorials skip, and it's the one that causes the most pain. The Midnight proof server requires significant memory — roughly 4GB under normal operation. WSL2's default memory limit is 50% of your physical RAM, capped at 8GB, but on machines with 8GB of total RAM the effective limit can be as low as 4GB with OS overhead consuming the rest. The proof server will OOM and crash silently, producing errors that look like network timeouts rather than memory failures.

Create or edit C:\Users\YourUsername\.wslconfig:

[wsl2]
memory=8GB
processors=4
swap=2GB
Enter fullscreen mode Exit fullscreen mode

Adjust memory based on your machine. The minimum for reliable proof server operation is 6GB. If you have 16GB of RAM, setting memory=10GB or memory=12GB gives you headroom.

After saving the file, shut down WSL completely and restart it:

wsl --shutdown
wsl
Enter fullscreen mode Exit fullscreen mode

Verify the memory limit inside WSL:

free -h
Enter fullscreen mode Exit fullscreen mode

The "total" row under "Mem" should reflect your .wslconfig setting.

Step 3: Install Docker Desktop with WSL2 Backend

Windows: Download and install Docker Desktop

Download Docker Desktop from the Docker website. During installation, select "Use WSL2 instead of Hyper-V" when prompted.

After installation, open Docker Desktop settings:

  1. Go to Settings → General
  2. Ensure "Use the WSL 2 based engine" is checked
  3. Go to Settings → Resources → WSL Integration
  4. Enable integration for your Ubuntu distribution

Click "Apply & Restart."

Verify Docker works from inside WSL:

docker run hello-world
Enter fullscreen mode Exit fullscreen mode

If you get a permission error, add your user to the docker group:

sudo usermod -aG docker $USER
Enter fullscreen mode Exit fullscreen mode

Then close and reopen your WSL terminal. The group change takes effect on new sessions.

Step 4: Install Node.js via nvm

WSL terminal

Do not install Node.js via apt. The version in Ubuntu's package manager is too old for Midnight's SDK. Use nvm to get a current version:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
Enter fullscreen mode Exit fullscreen mode

Close and reopen your terminal, then install Node.js 20:

nvm install 20
nvm use 20
nvm alias default 20
Enter fullscreen mode Exit fullscreen mode

Verify:

node --version  # Should print v20.x.x
npm --version
Enter fullscreen mode Exit fullscreen mode

Step 5: Install the Compact Compiler

WSL terminal

The Compact compiler is distributed as a tar archive. Download it from the Midnight documentation site or the release assets linked in the Midnight contributor hub. At time of writing, the installer is:

# Check https://docs.midnight.network for the current release URL
curl -L -o compact-compiler.tar.gz <URL from midnight docs>
tar -xzf compact-compiler.tar.gz
cd compact-compiler
chmod +x install.sh
./install.sh
Enter fullscreen mode Exit fullscreen mode

The installer puts the compactc binary somewhere under ~/.local or a path it tells you during installation. If it doesn't automatically add this to your PATH, add it manually:

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

Verify:

compactc --version
Enter fullscreen mode Exit fullscreen mode

If compactc is not found, use find ~ -name compactc 2>/dev/null to locate the binary and add its directory to PATH.

Step 6: Clone a Project and Run the Local Stack

WSL terminal

Clone the Midnight examples repository inside your WSL filesystem. Do not clone into /mnt/c/ or any Windows-mounted path — Docker and the proof server have poor performance with Windows filesystem paths, and some tools behave incorrectly with Windows line endings.

cd ~
git clone https://github.com/midnightntwrk/midnight-js-examples.git
cd midnight-js-examples
npm install
Enter fullscreen mode Exit fullscreen mode

The Midnight local development stack runs via Docker Compose. Start it:

docker compose up -d
Enter fullscreen mode Exit fullscreen mode

This pulls and starts several containers: the Midnight node, the indexer, and the proof server. The first pull will take several minutes. Subsequent startups are fast.

Wait for the stack to be healthy:

docker compose ps
Enter fullscreen mode Exit fullscreen mode

All services should show "healthy" status. The proof server takes the longest — it loads a large proving key on startup. Give it 60–90 seconds before expecting it to be ready.

Step 7: Compile and Deploy a Contract

WSL terminal

With the local stack running, compile one of the example contracts:

cd examples/hello-world
npx compile
Enter fullscreen mode Exit fullscreen mode

The compile script runs compactc against the .compact source files and generates TypeScript bindings. If this fails with "command not found," your compactc PATH setup from Step 5 is incomplete.

Deploy to the local stack:

npx ts-node src/index.ts
Enter fullscreen mode Exit fullscreen mode

A successful run produces output showing the deployment transaction hash and the deployed contract address. If you see errors about connection refused on port 9944 (the node RPC), the Docker stack isn't healthy yet — wait a bit longer and try again.

Troubleshooting

Proof server crashes or times out

This is almost always a memory issue. The proof server loads a large proving key into RAM. If WSL doesn't have enough memory, the process gets OOM-killed without a useful error message.

Check available memory:

free -h
Enter fullscreen mode Exit fullscreen mode

If available memory is low, increase the memory setting in .wslconfig and restart WSL with wsl --shutdown from a Windows terminal, then wsl to restart.

Docker commands fail with "permission denied"

You need to be in the docker group. Run groups to check your current group membership. If docker isn't listed, run:

sudo usermod -aG docker $USER
Enter fullscreen mode Exit fullscreen mode

Then log out and back into WSL (close the terminal and open a new one).

compactc not found after installation

The installer may have put the binary in a directory not on your PATH. Run:

find ~ -name compactc 2>/dev/null
Enter fullscreen mode Exit fullscreen mode

Add the directory containing compactc to your PATH in ~/.bashrc.

Localhost ports not accessible from Windows browser

When you run a development server inside WSL (like a frontend at localhost:3000), it should be accessible from your Windows browser at localhost:3000. If it isn't, check that you're binding to 0.0.0.0 rather than 127.0.0.1 in your server configuration.

WSL2 runs in a lightweight VM with its own network interface. The Windows host can reach WSL services through port forwarding that Windows sets up automatically, but only for services bound to all interfaces.

Slow performance when working in /mnt/c/

This is expected. The /mnt/c/ mount uses a filesystem translation layer that is significantly slower than the native Linux filesystem. Keep all your Midnight project files under ~/ (your Linux home directory) and use a code editor that supports WSL remote development (VS Code with the WSL extension works well for this).

Accessing WSL Files from Windows

VS Code with the Remote - WSL extension is the recommended editor setup. Install the extension, then from your WSL terminal:

code .
Enter fullscreen mode Exit fullscreen mode

This opens VS Code on the Windows side connected to your WSL filesystem. You get full editor features (IntelliSense, debugging, terminal) without the performance penalty of working through the Windows filesystem mount.

Summary

The setup requires more steps than the documentation suggests, but once it's working it's solid. The three things that trip people up most:

  1. Memory: Always configure .wslconfig with enough memory for the proof server before starting anything.
  2. Filesystem: Keep projects in ~/ not in /mnt/c/ or any Windows mount.
  3. PATH: Manually add compactc to PATH if the installer doesn't do it automatically.

After that, the Midnight toolchain works exactly as described in the Linux documentation. Every tutorial, example, and SDK reference applies without modification.

Top comments (0)