DEV Community: Just_a_kumar

Building an AI Subtitle App with Next.js and SigNoz (With Plenty of Docker Debugging Along the Way)

Just_a_kumar — Sat, 25 Jul 2026 23:42:33 +0000

My AI subtitle generator works. Right now, if I upload a video, Next.js processes it, OpenTelemetry captures every span along the way, and SigNoz shows me the whole thing as a live distributed trace. That part's real and it's done.

What I didn't expect is that getting SigNoz itself to behave would turn into its own separate project — one fought entirely in Docker volumes, a login screen that made no sense, and a PowerShell terminal that hated me personally. This is the honest version of that story: not a clean tutorial, but what actually happened.

The Success, Up Front

Because I don't want this to read like a two-thousand-word bug report: it worked. The app takes a video upload, kicks off backend processing to generate cinematic AI-style subtitles, and every one of those steps — upload, processing request, whatever happens in between — shows up as a real trace in SigNoz's Traces Explorer. That was the actual goal of the hackathon submission, and I hit it.

But I want to be upfront that the road there was not smooth, and I think the messy part is more useful to write about than the finished screenshot. If you're about to self-host SigNoz for the first time, the app code is not going to be your hard part. Your local environment is.

What I Built and Why Tracing Actually Mattered Here

The project itself: a Next.js web app that takes a video upload and automatically generates cinematic, AI-style subtitles for it. Sounds like one feature, but it's really a pipeline — a file comes in, gets handed off for backend processing, something transcribes/times the audio, something else styles the subtitle output, and eventually a result comes back to the user. Every one of those steps can fail or slow down on its own, and without visibility into which step, "my video is stuck processing" just means staring at a spinner and guessing.

So the plan was straightforward: instrument the app with OpenTelemetry so every upload and processing request generates a real trace, run those traces into a local SigNoz stack, and actually see the pipeline instead of adding console.log statements and hoping.

The Stack

App layer: Next.js, instrumented with OpenTelemetry so uploads and backend processing requests each produce spans and a trace.
Observability backend: SigNoz, self-hosted locally.
Storage: ClickHouse for the telemetry data itself (traces/metrics/logs), PostgreSQL for user and metadata storage.
Orchestration: Docker containers, spun up and managed through Foundry using a config file we named casting.yaml.

We used Foundry as a wrapper around Docker Compose to easily orchestrate and manage our multi-container stack from a single casting.yaml file.

For the instrumentation itself, I used the instrumentation.ts convention Next.js picks up automatically, with @vercel/otel handling the SDK wiring instead of me hand-rolling the whole OpenTelemetry setup:

// instrumentation.ts (project root)
import { registerOTel } from '@vercel/otel';

export function register() {
  registerOTel({
    serviceName: 'subtitle-studio',
  });
}

# .env.local
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

That part, honestly, was the easy part. It's well-documented, it's a known pattern, and it worked close to the first try. The infrastructure underneath it is where things got real.

The Gritty Middle: When Your Own Local Environment Becomes the Boss Fight

Here's the thing nobody really warns you about with local observability stacks: the app code is the small problem. The stack running underneath it — the containers, the volumes, the state that quietly persists between runs — is where you actually lose your evening.

I brought the SigNoz stack up through Foundry (foundryctl.exe cast -f casting.yaml), fully expecting the standard first-run experience: a setup wizard, create an admin account, done. Instead I got bounced straight to /login with a message telling me self-registration was disabled.

I want to sit on that for a second because it's such a specifically confusing error to get on what I thought was a brand-new install. Self-registration disabled implies someone already registered. I hadn't. Nobody had. Except — and this took me embarrassingly long to piece together — my Docker volumes disagreed. They were holding onto state from an earlier attempt at standing this stack up, an attempt where an org and an admin account had technically already been created. So SigNoz wasn't lying to me. It was correctly telling me it was already initialized. I just had zero credentials for the version of the world it remembered.

This is the part of local infra work that I think is genuinely harder than writing application code: the bug isn't in front of you, it's behind you, sitting in a volume you forgot existed from a run you forgot you did.

My first instinct was to patch around it instead of admitting the environment was compromised — because tearing everything down and starting over felt like giving up.

Attempt one: dig through environment variables related to auth/registration, on the theory there was a flag somewhere I could just flip back to "allow registration." No dice — the state causing the problem wasn't in an env var, it was already sitting in the database.

Attempt two: go straight into Postgres and manually INSERT an admin row myself. This is where I properly hit a wall. SigNoz's schema has real relational constraints — an org, an admin, and a user aren't three independent rows you can fake into existence, they're expected to be created together through the app's own flow. My hand-written insert kept getting rejected by schema constraints it had every right to reject me on.

Attempt three, which somehow made it worse: I was doing all of this from PowerShell, and trying to escape a multi-field SQL statement's quotes correctly through PowerShell's quoting rules turned into a fully separate debugging side-quest that had nothing to do with SigNoz at all. I burned real time just trying to get a single INSERT statement to survive the terminal without PowerShell mangling the quotes.

At this point I'd spent more time fighting my own terminal than I had setting up the actual tracing. That's the part I want other people attempting this to know going in: local debugging on a self-hosted observability stack can absolutely eat more time than the feature you're trying to observe.

The Turn: Stop Patching, Wipe the Slate

Eventually I stopped trying to be clever about it. If the environment itself was the problem, patching the environment wasn't going to fix it — I needed to actually reset it.

docker compose down
docker volume prune
foundryctl.exe cast -f casting.yaml

Stopping the containers and pruning the volumes genuinely wiped the leftover ClickHouse and Postgres data instead of leaving ghosts behind for the next run to trip over. Re-casting the stack from casting.yaml afterward gave me an actually-fresh instance — and this time SigNoz served up the real first-run setup wizard instead of bouncing me to a login screen for an account I didn't have.

There's a specific kind of relief in watching a setup wizard appear where a broken login screen used to be. It's a small thing, but after that stretch of fighting SQL constraints and PowerShell quoting, it felt like an actual win.

I created my admin account, and — because this weekend clearly wasn't done testing me — SigNoz threw a ClickHouse metadata error on first boot while its container init scripts were still finishing structuring the schema. This time, though, I didn't panic and start patching. I recognized it for what it was: the database still setting itself up. I let it finish. It resolved on its own once ClickHouse had fully initialized its tables.

The Relatable Win

Then the actual payoff: I uploaded a test video through the Next.js app and watched a real trace land in SigNoz's Traces Explorer at http://localhost:8080/traces-explorer — the upload request and the backend processing request, connected, with real timing data sitting right there on screen.

Not going to pretend that wasn't a genuinely good moment. After a stretch of ghost data, schema constraint errors, and quoting fights that had nothing to do with the actual project, seeing a real trace show up — one that mapped to a video I'd just uploaded, seconds earlier — was the first time the whole weekend felt like it was working for me instead of against me.

What I Actually Learned

A confusing auth error is often stale state, not broken config. The self-registration message sent me looking at auth settings first, when the real issue was Docker volumes remembering a previous run. If a "fresh" deploy behaves like it isn't fresh, check the volumes before you touch any code or config.
Don't hand-write inserts into a system with real schema relationships. SigNoz expects org/admin/user creation to happen through its own flow. A manual INSERT was never going to be a clean shortcut, and I lost real time learning that the hard way.
PowerShell quoting is a tax on anything multi-field. Next time I'd write inline SQL/JSON to a file and pipe it in rather than fight inline escaping in the terminal.
docker volume prune + re-cast beat every "smart" fix combined. The fastest debugging move was admitting the environment itself was the bug and rebuilding it, instead of trying to outsmart it in place.
Local infra debugging can genuinely be harder than the application code. Writing the OpenTelemetry instrumentation was a known, documented pattern that mostly just worked. Getting the observability backend into a clean, working state was where all the real friction lived — and I don't think that's talked about enough going into a project like this.
It was worth it. Once traces were flowing, "is the upload slow or is processing slow" stopped being a guess and became something I could just look at.

If I did this again, I'd write down the "nuke it and re-cast" steps before trying anything clever with env vars or manual SQL — because that's what I ended up doing anyway, just an hour later than I needed to.

Wrapping Up

The finished result: a working local SigNoz setup tracking real video-processing traces, with no errors, for an app that actually does what it's supposed to do. Getting there meant fighting through stale Docker state, a login wall I didn't expect, schema constraints, and a PowerShell quoting battle that had nothing to do with observability at all — and then winning that fight with a clean wipe and a re-cast. That's the real version of how this project came together, mess and all.

Demo video: https://youtu.be/jElGmQRMbYY?si=kaG_rNgswtF09mdQ
Project repo: https://github.com/justkidding998877665544332211/ai-subtitles-studio-signoz
OpenTelemetry docs (for anyone instrumenting Next.js themselves): https://opentelemetry.io
SigNoz's own Next.js + OpenTelemetry guide: https://signoz.io/docs/instrumentation/javascript/opentelemetry-nextjs/

Pushing SigNoz Foundry as a Complete DevOps Beginner Until My RAM Broke (and How I Fixed It)

Just_a_kumar — Sun, 19 Jul 2026 18:29:07 +0000

Introduction

If you're a complete beginner, the backend of software feels like literal black magic. You click a single button on a sleek frontend interface, and suddenly a massive web of microservices starts yelling at each other, querying databases, and moving heavy data streams under the hood. Standard debugging tools rarely show you why a specific action is lagging or exactly where the architecture is screaming for help.

When the WeMakeDevs team dropped the "Agents of SigNoz" hackathon, I saw the perfect excuse to step outside my comfort zone and dive into open-source observability. My mission was simple on paper: self-host SigNoz on my local machine using their brand-new CLI installer, Foundry.

It did not go smoothly. Over the course of this deployment I hit a shell compatibility error, a broken Docker-to-WSL bridge, a permissions wall, and finally a hard out-of-memory crash that killed the whole process right as it was about to finish. But I didn't stop at the crash — I went back, found the actual root cause of each problem, fixed them properly instead of just working around them, and got SigNoz fully running with real trace data flowing into it. This post walks through every one of those failures in order, what actually caused each one, and exactly how I fixed it.

Prerequisites

BBefore you break things the way I did, make sure you have this on your Windows machine:

Docker Desktop, with the engine actually running (not just installed)
WSL 2 with an active Ubuntu distro
VS Code, mainly for its terminal profile switcher

Problem 1: The Wrong Shell

The hackathon explicitly required using SigNoz's new CLI tool, Foundry. The official docs gave a one-line install command:

curl -fsSL [https://signoz.io/foundry.sh](https://signoz.io/foundry.sh) | bash

I pulled up my VS Code terminal, pasted it, hit Enter — and got an error saying it couldn't find a parameter matching -fsSL.

The cause: My default VS Code terminal was PowerShell, not a Linux shell. PowerShell aliases curl to Invoke-WebRequest, which has no idea what -fsSL means because those are curl-specific flags from Linux.

The fix: I switched the terminal profile in VS Code to Ubuntu (WSL) and re-ran the exact same command. It worked immediately.

Problem 2: The Broken Docker Bridge

With Foundry installed, I wrote a small YAML blueprint (casting.yaml) telling it to deploy SigNoz via Docker:

apiVersion: v1alpha1
kind: Installation
metadata:
  name: signoz
spec:
  deployment:
    flavor: compose
    mode: docker

Running foundryctl cast -f casting.yaml immediately failed — the terminal said it couldn't find docker-compose. Docker Desktop was running fine on the Windows side, but WSL had no idea it existed.

The cause: Docker Desktop and WSL don't talk to each other by default. You have to explicitly bridge them.

The fix:Docker Desktop → Settings → Resources → WSL Integration → toggle on "Enable integration with my default WSL distro," enable Ubuntu specifically, then Apply & Restart.

Problem 3: The Permission Wall

With the bridge fixed, I re-ran the deploy and hit a new error:

unable to get image... permission denied while trying to connect to the Docker API at unix:///var/run/docker.sock

The cause: My Linux user didn't have permission to talk to the Docker daemon's socket. This is standard Docker behavior on a fresh Linux setup — only root or members of the docker group can use the Docker CLI without extra steps.

The quick-and-dirty fix I used at first: I forced it through with sudo and the absolute path to the binary:

sudo /home/idiot/.local/bin/foundryctl cast -f casting.yaml

That got the deploy moving again, but it's not the right long-term fix — running Docker commands as root for every single call isn't something you want to make a habit of.

Problem 4: The Out-of-Memory Crash

Past the permission wall, the deploy connected to the Docker registry and started pulling the backend images — Postgres, the OpenTelemetry collector, ClickHouse. Right at the finish line, it stopped dead:

"exception": {
  "message": "signal: killed"
}

The cause: My machine ran out of RAM trying to unpack all those container layers at once — ClickHouse especially is not lightweight. Windows killed the process to protect itself before I could kill it myself.

At first I read this as a hardware limitation and wrote it off. It isn't. WSL 2 caps how much RAM it'll allocate to the Linux VM by default, and that cap is often too conservative for a multi-container stack like SigNoz's — it's a configuration ceiling, not a physical one.

The real fix: create (or edit) a .wslconfig file in the Windows user directory:

notepad "$env:USERPROFILE\.wslconfig"

Notepad will offer to create it — say yes, then paste:

[wsl2]
memory=8GB
processors=4
swap=4GB

Save, then restart WSL from PowerShell so the change actually applies:

wsl --shutdown

Reopening the terminal and checking free -h confirmed the new memory ceiling had taken effect.

Fixing Problem 3 Properly

Before re-running the deploy, I went back and fixed the permissions issue the right way instead of relying on sudo:

sudo usermod -aG docker $USER

Group membership changes don't apply to an already-open terminal session — I had to fully close the terminal tab and open a fresh one for it to take effect. After that, docker ps worked with no sudo and no permission error.

The Clean Re-Run

With the memory ceiling raised and permissions fixed properly, I cleared out any half-downloaded layers from the earlier crash:

docker system prune -a

Then ran the deploy again, this time with no sudo and no workarounds:

foundryctl cast -f casting.yaml

This time it completed cleanly — every image pulled, every container started or reported healthy, no OOM kill.

Getting Into the Dashboard

With everything running, I opened http://localhost:8080 and landed on SigNoz's account setup screen.

After creating an account, I was in — but the dashboard was empty, with a message saying no data had been sent yet. Standing the tool up was only half the job; nothing shows up in an observability platform until something is actually instrumented and pointed at it.

Getting Real Data Flowing

To generate real trace data without building a project from scratch, I used Jaeger's HotROD demo app — a small pre-built microservices app made specifically for testing tracing setups. My first attempt at running it didn't send any data anywhere, because I hadn't told it where SigNoz's collector actually was:

docker run --rm -d --name hotrod \
  --network signoz-network \
  -p 8081:8080 \
  jaegertracing/example-hotrod:latest \
  all

The fix: HotROD needs to be told explicitly where to send its OTLP trace data. I found the right container name by listing what Foundry had actually deployed:

docker ps --format "table {{.Names}}"

and pointed HotROD at the ingester service on the same Docker network:

docker stop hotrod

docker run --rm -d --name hotrod \
  --network signoz-network \
  -p 8081:8080 \
  --env OTEL_EXPORTER_OTLP_ENDPOINT=http://signoz-ingester-1:4318 \
  jaegertracing/example-hotrod:latest \
  all

(Worth being upfront about: HotROD is Jaeger's example app, not something built by or for SigNoz — I used it purely as a traffic generator to prove the pipeline actually works end to end, not as part of a custom project.)

I opened http://localhost:8081 and clicked through a few "call a car" requests for different customers to generate multiple traces.

The Payoff

Back in SigNoz's Traces Explorer, real spans had landed — service names like route and frontend, real durations, real HTTP status codes. Not a mock, not a placeholder. An actual working observability pipeline, built from a machine that had OOM-crashed on the exact same deployment less than an hour earlier.

What I Learned

Shell context matters more than the command itself. The exact same string can fail or succeed depending on whether PowerShell or a real Linux shell is interpreting it.
Docker on WSL is really two systems shaking hands, and either side — the bridge, or the socket permissions — can quietly block you without an error message that points at the real cause.
"Out of memory" isn't always a hardware problem. On WSL 2 specifically, it's frequently a configuration default, not a physical limit. Checking .wslconfig costs two minutes and can save you from wrongly concluding your machine just isn't capable.
sudo is a workaround, not a fix. It got me unblocked in the moment, but usermod -aG docker is the version of that fix worth actually keeping.
Deploying the tool and using the tool are two different milestones. SigNoz being "up" and SigNoz actually showing you something are separated by one more step most tutorials skip past: getting real telemetry pointed at it.

Conclusion

I started this deployment expecting a quick CLI install and ended up debugging shell environments, Docker-to-WSL networking, Unix socket permissions, and a memory ceiling I initially mistook for a hardware wall — before finally watching real trace data land in a dashboard that, an hour earlier, hadn't even been able to finish installing. Every fix here came from actually reading the error instead of guessing, which is probably the most useful thing I'm walking away with — that, and a .wslconfig file I'm never deploying anything heavy without again.

Resources: