Before I saw a single trace inside SigNoz, my laptop said no to me three times in a row. First Docker said no. Then WSL said no. Then permissions said no. I had a completely empty Windows machine, a hackathon to prepare for, and a growing feeling that this was going to be a long evening.
It was. But by the end I had my own SigNoz dashboard running locally, and every error had a fix that turned out to be simpler than the panic it caused. If you are self-hosting SigNoz on Windows for the first time, this is the walkthrough I wish someone had handed me.
WHAT I DID...
The plan and the tools that make it work
The goal was simple on paper to get SigNoz an open-source, OpenTelemetry-native observability platform running on my own machine so I could build on top of it later. Three pieces make that happen, and it helps to know what each one does before things start breaking:
• Docker runs SigNoz's many parts inside isolated containers, so you don't install a dozen things by hand.
• WSL 2 is a real Linux environment living inside Windows. Docker leans on it.
• Foundry is SigNoz's official installer. You hand it one config file and it brings the whole stack up.
That config file is almost comically small. This is the entire thing that boots SigNoz and its MCP server:
apiVersion: v1alpha1
kind: Installation
metadata:
name: signoz
spec:
deployment:
mode: docker
flavor: compose
mcp:
spec:
enabled: true
I read that, thought "this looks easy," and confidently ran into my first wall.
👊Round 1 "WSL is not installed"
I installed Docker Desktop, opened it, and it stopped almost instantly..
Windows Subsystem for Linux (WSL) is not installed.
I hadn't even typed a single command yet, and something was already red on my screen. Not the confident start I had pictured.
The fix is one line. Open PowerShell as administrator and run..
wsl --install
It pulls down WSL 2 and Ubuntu, then asks you to create a Linux username and password. The password shows nothing as you type no dots, no stars which threw me for a second until I realised that is just how Linux takes passwords. Then it told me to restart.
The gotcha 😌: you truly have to restart the PC here. I tried to skip it and reopen Docker straight away, and it simply refused to see WSL. Restart, then continue.
🖐️Round 2 "docker-compose could not be found"
After the restart I set Foundry up downloaded it, made it runnable, dropped in the casting.yaml from earlier and ran the install..
foundryctl cast -f casting.yaml
It Denied again:
The command 'docker-compose' could not be found in this WSL 2 distro. We recommend to activate the WSL integration in Docker Desktop settings.
Second error, and this one at least had the decency to tell me where to look. My Ubuntu and my Docker were installed, but they were not talking to each other yet. There is a switch for exactly this.
In Docker Desktop: Settings → Resources → WSL Integration. Turn on "Enable integration with my default WSL distro," flip the Ubuntu toggle on, and hit Apply & restart.
✌️Round 3 "Permission denied"
Confidence restored, I ran the install a third time. And got hit a third time:
unable to get image 'signoz/signoz-mcp-server:latest': permission denied while trying to connect to the Docker API at unix:///var/run/docker.sock
Three errors in a row. At this point I was fully convinced I had broken something deep and was about to spend the night reinstalling everything.
But look closely.. the error had changed. It was no longer "can't find docker," it was "not allowed to use docker." That is progress in disguise: the previous fix had worked, and now Ubuntu just lacked permission. Two steps solve it. First, add your user to the docker group.
sudo usermod -aG docker $USER
Then the part that actually caught me you must fully restart WSL for that new permission to load. In PowerShell..
wsl --shutdown
Wait ten seconds, reopen Ubuntu, and the permission is live.
Small thing worth knowing 😉: group changes only apply to a fresh session. On most Linux systems you would run newgrp docker to refresh instantly, but my Ubuntu didn't have it, so a full wsl --shutdown is the clean way to force it.
The moment I clicked...
One more run of the same command:
foundryctl cast -f casting.yaml
And this time green. Progress bars everywhere. Foundry pulled every image in the stack (postgres, ClickHouse, the SigNoz app, the OTel collector, the MCP server) and started them one by one. Then the line I had been fighting for.
[+] up 82/82 ...
Container signoz-signoz-0 Started
Container signoz-telemetrystore-clickhouse-0-0 Started
Eighty-two out of eighty-two. After an hour of "no," seeing everything come up green was genuinely satisfying.
Finally I did it...
I opened localhost:8080, created a local account, and there it was my own SigNoz workspace, running entirely on my laptop.
It politely notes "you're not sending any data yet," which is exactly right nothing is reporting to it so far. Wiring a real app into it is the next chapter, during the hackathon build itself.
What I'd tell my past self...
• Restarts are not optional. Two of my three errors were really "you didn't restart the thing that needed restarting." After WSL installs, restart the PC. After permission changes, wsl -- shutdown .
• Read the error before you panic. Every single message here basically told me the next move. The delay was me reacting, not the tool being cryptic.
• A changed error means you're winning. When "can't find docker" became "not allowed to use docker," that felt like another failure. It was actually the sound of the previous fix working.
In The End...
So that's my honest first hour with SigNoz on Windows: three errors, three fixes, and a live dashboard waiting for data at the end. It worked on my setup (Windows 11 + WSL 2 + Docker Desktop); yours may differ a little, but these fixes should point you in the right direction. Next up, I feed it real telemetry and start building my actual hackathon project on top and yes, I'll write about that part too.
If you hit these same three walls, I hope this saved you the hour it cost me. If it did, drop a comment and tell me what you're building with SigNoz.
Written by...Tarun Mhanta an MCA student in Cybersecurity & AI who likes building things and writing about what breaks along the way. Currently gearing up for the Agents of SigNoz hackathon. Say hi: GitHub @tarunmhanta30 ·
Top comments (0)