DEV Community

Cover image for Installing SigNoz on Windows: the Fastest Way (5 Minutes, No Docker Desktop)
Metta Surendhar
Metta Surendhar

Posted on • Originally published at Medium

Installing SigNoz on Windows: the Fastest Way (5 Minutes, No Docker Desktop)

#signoz #foundry #installation #windows

If you’ve looked at SigNoz’s install docs, you’ve probably noticed something. There’s no “Windows” tab. That’s because Windows isn’t officially supported, so you need a Linux environment underneath it, one way or another.

I went through this myself this week, hit a few things worth flagging, and figured I’d write down the exact path that actually works: fast, free, and without the one Windows-specific trap that’ll cost you an hour if you don’t know about it upfront.

The ways to install SigNoz

Before picking one, here’s the full menu, so you know what you’re opting into:

  • Docker Compose (via Foundry): single machine, fastest to stand up, what we’re doing today
  • Kubernetes / Helm: if you already run a cluster and want SigNoz alongside your other workloads
  • systemd / bare metal: installing directly onto a Linux VM without containers
  • Docker Swarm: multi-node, production-leaning
  • A free-tier cloud VM (e.g. Oracle Cloud’s always-free tier): skip Windows/WSL entirely, run a genuine free Linux VM and install SigNoz there instead
  • SigNoz Cloud: fully hosted, zero install, but it’s a 30-day free trial, not free forever

For a local dev/hackathon setup on Windows, Docker Compose is the easiest, and it’s genuinely free with no trial clock. Here’s the whole path, start to finish.

1. Check your WSL version

Open PowerShell and run:

wsl --version
Enter fullscreen mode Exit fullscreen mode

If that errors out, you don’t have WSL yet. No problem, next step installs it.

2. Install Ubuntu on WSL2

Still in PowerShell (as Administrator):

wsl --install -d Ubuntu-24.04
Enter fullscreen mode Exit fullscreen mode

Restart if it asks you to.

On first launch, it’ll ask you to set a username/password for your Linux user. That’s separate from your Windows login.

Memory note: WSL2 auto-allocates up to about half your system RAM by default. SigNoz’s containers need roughly 4GB free to run comfortably, so if your machine has 8GB total, keep an eye on things. You can cap or raise WSL’s memory limit later via a .wslconfig file if needed.

3. (Optional) Move it to a different drive

By default WSL installs onto your C: drive. If you’d rather keep it elsewhere, here’s how I moved mine to D:\WSL\Ubuntu:

mkdir D:\WSL\Ubuntu
wsl --export Ubuntu-24.04 D:\WSL\ubuntu_backup.tar
wsl --unregister Ubuntu-24.04
wsl --import Ubuntu D:\WSL\Ubuntu D:\WSL\ubuntu_backup.tar
Enter fullscreen mode Exit fullscreen mode

Skip this if C: has room to spare.

One gotcha with imported distros:

They default to logging you in as root instead of your own user. Fix it by opening the distro and editing its config:

wsl -d Ubuntu
Enter fullscreen mode Exit fullscreen mode

This drops you into the Ubuntu terminal, which is also how you’ll re-enter it every time going forward. Once inside:

echo -e "[user]\ndefault=<your-username>" | sudo tee -a /etc/wsl.conf
Enter fullscreen mode Exit fullscreen mode

Then from PowerShell:

wsl --shutdown
Enter fullscreen mode Exit fullscreen mode

Reopen with wsl -d Ubuntu and you'll land as your own user from now on.

4. Docker Desktop or Docker Engine? Pick Engine.

This is the trap I mentioned. It’s tempting to just install Docker Desktop since it’s the familiar Windows-friendly option, but SigNoz’s own docs specifically call out a known issue. ClickHouse Keeper (part of SigNoz’s storage layer) has been reported to crash in a restart loop under Docker Desktop’s virtualization layer on Windows.

Installing Docker Engine directly inside WSL sidesteps this entirely, and it’s barely more work.

From inside your Ubuntu (WSL) terminal:

Quick way :
(Docker’s own official convenience script, fine for dev/hackathon boxes)

curl -fsSL https://get.docker.com | sh
Enter fullscreen mode Exit fullscreen mode

Or the fuller, version-pinned way :
(Worth doing if this becomes a permanent setup rather than a one-off hackathon box)

sudo apt-get install ca-certificates curl gnupg -y
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
Enter fullscreen mode Exit fullscreen mode

Either way, each SigNoz container is fairly light individually, but ClickHouse (the storage backend) is the heaviest piece. Budget about 4GB overall for the full stack.

Verify Docker’s actually working:

docker run hello-world
Enter fullscreen mode Exit fullscreen mode

If that prints its welcome message, you’re good.

5. Let your user run Docker without sudo 

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

Close and reopen your WSL terminal for this to take effect.

6. What’s Foundry?

Foundry is SigNoz’s own installer/deployment tool. One CLI (foundryctl) that generates and runs the right Docker Compose (or Kubernetes, or systemd) setup for you, based on a small config file called a casting. For the full concepts, Foundry's docs are worth a read. Here's just enough to get running.

Install Foundry : 

curl -fsSL https://signoz.io/foundry.sh | bash
Enter fullscreen mode Exit fullscreen mode

Export path : 

export PATH="/home/<your-unix-username>/.local/bin:$PATH"
Enter fullscreen mode Exit fullscreen mode

7. Write your casting file

A casting is just a YAML file describing how you want SigNoz deployed. This is the minimal version:

mkdir ~/signoz && cd ~/signoz
cat > casting.yaml << 'EOF'
apiVersion: v1alpha1
metadata:
  name: signoz
spec:
  deployment:
    mode: docker
    flavor: compose
EOF
Enter fullscreen mode Exit fullscreen mode

There’s a lot you can customize here, like retention periods, resource limits, and individual component configs, but this is all you need to get your first instance running. Foundry’s casting concepts doc covers the rest if you want to go deeper later.

8. Deploy 

foundryctl cast -f casting.yaml
Enter fullscreen mode Exit fullscreen mode

This checks your prerequisites, generates the actual Compose files, and starts everything in one command.

9. Verify and see it running 

docker ps
Enter fullscreen mode Exit fullscreen mode

Everything should show Up. Then, in your regular Windows browser, go to:

http://localhost:8080
Enter fullscreen mode Exit fullscreen mode

WSL2 forwards localhost to Windows automatically, so no extra networking setup needed. You should land straight on SigNoz’s UI.

That’s it

About 5 minutes of reading, 2 minutes of actually typing commands, and you’ve got a fully self-hosted, genuinely free SigNoz instance running on Windows. No Docker Desktop bug to debug, no trial clock running out on you. Next up for me: getting my first real trace into it.

Top comments (0)