DEV Community: Amorizz

Sentry caught my Express error. The request still hung forever

Amorizz — Fri, 16 Oct 2026 20:10:32 +0000

I assumed that with an error SDK installed, an async Express route that throws would at least give the user a 500. I had never tested it, so I did. The result surprised me.

The short version: on Express 4, an async handler that throws after an await is reported by Sentry, keeps the process alive, and never answers the request. The client just waits.

Everything below was run on 2026-10-16 on a Linux box with Node 20.19.2, Express 4.22.3, Express 5.3.0 and @sentry/node 11.8.0. The "Sentry server" is a throwaway 15-line Node script on localhost, so nothing leaves the machine. Outputs are pasted from the runs, with log noise trimmed.

TL;DR

Express 4 does not look at the promise your async handler returns. A throw after an await becomes an unhandled rejection, not a next(err) call.
Without an error SDK, Node 20 kills the process. With @sentry/node initialised, the process survives, the error is reported, and the request hangs. That is the nasty one, because everything looks healthy.
Fix on Express 4: wrap the handler and .catch(next). Or move to Express 5, where rejected promises go to your error handler on their own. The Express docs describe the Express 5 behaviour in their error handling guide.

The smallest app that reproduces it

// app.js
const express = require('express');
const app = express();
const sleep = (ms) => new Promise(r => setTimeout(r, ms));

if (process.env.SENTRY) {
  const Sentry = require('@sentry/node');
  global.Sentry = Sentry;
  Sentry.init({ dsn: 'http://key@127.0.0.1:9999/1', tracesSampleRate: 0 });
}

app.get('/sync',  () => { throw new Error('sync boom'); });
app.get('/async', async () => { await sleep(10); throw new Error('async boom'); });
app.get('/ok',    (req, res) => res.send('ok'));

if (process.env.SENTRY) global.Sentry.setupExpressErrorHandler(app);

app.use((err, req, res, next) => {
  console.log('[error middleware]', err.message);
  res.status(500).send('handled');
});

app.listen(3000);

Two routes that throw. One throws right away. The other throws after a 10 ms await, which is what any real handler does the moment it calls a database.

And the "Sentry server", just enough to see what arrives:

// sink.js
const http = require('http'), zlib = require('zlib');
http.createServer((q, r) => {
  const b = [];
  q.on('data', c => b.push(c));
  q.on('end', () => {
    let buf = Buffer.concat(b);
    try { buf = zlib.gunzipSync(buf); } catch {}
    for (const l of buf.toString().split('\n').filter(Boolean)) {
      try {
        const j = JSON.parse(l);
        if (j.exception) {
          const e = j.exception.values[0];
          console.log('SINK event:', e.type, e.value, 'mech=', e.mechanism && e.mechanism.type);
        }
      } catch {}
    }
    r.end('{}');
  });
}).listen(9999);

The test is the same every time: start the app, curl the sync route, curl the async route with -m 5, then curl /ok to see if the server is still alive.

Run 1: Express 4, no SDK

GET /sync  -> http=500 curl_exit=0
GET /async -> http=000 curl_exit=52
GET /ok afterwards -> (curl_exit=7)
process: dead

[error middleware] sync boom
/app.js:10
app.get('/async', async () => { await sleep(10); throw new Error('async boom'); });
                                                       ^
Error: async boom
Node.js v20.19.2

The sync throw gets a clean 500 from my error middleware. The async one never reaches it. Node 20 treats the unhandled rejection as fatal and the whole process exits. The client sees an empty reply (curl exit 52) and the next request is refused (exit 7).

That is loud, at least. Your process manager restarts it and you notice.

Run 2: Express 4, with Sentry

Same app, SENTRY=1:

GET /sync  -> http=500 curl_exit=0
GET /async -> http=000 curl_exit=28
GET /ok afterwards -> ok (curl_exit=0)
process: alive

SINK event: Error sync boom  mech= auto.middleware.express
SINK event: Error async boom mech= auto.node.onunhandledrejection

Exit code 28 is curl giving up after my 5 second limit. The error was reported. The process did not crash. And the request got nothing.

Two things I noticed in the output:

The sync error came in through auto.middleware.express, meaning the Express error handler saw it. The async one came in as auto.node.onunhandledrejection. Sentry caught it, but from the global rejection hook, not from Express.
The app log shows Node's usual "This error originated either by throwing inside of an async function without a catch block" warning, and then nothing else. The process keeps running.

To check this is a real hang and not a slow response, I left one request open for 25 seconds. curl timed out at 25.0 s with no status code, and ss still showed one established connection on port 3000 twenty seconds in. The socket stays open until the client or a proxy gives up.

So the SDK did its job. It reported the error and kept my process alive. What it cannot do is write a response for a request Express no longer knows about. In production that "stays up" behaviour is what turns a crash into a silent hang, and the hang is probably cut off by your load balancer's idle timeout, not by anything in your app. I did not test a proxy here, so I can't tell you what yours does.

Run 3: Express 5

I made a second project with Express 5.3.0 and the same app.js:

GET /sync  -> http=500 curl_exit=0
GET /async -> http=500 curl_exit=0
GET /ok afterwards -> ok (curl_exit=0)
process: alive

[error middleware] sync boom
[error middleware] async boom

With Sentry on, both events arrive with mech= auto.middleware.express. The async error goes through my error middleware, the client gets a 500, and nothing hangs.

This matches what the Express docs say: route handlers that return a promise call next(value) when they reject, and async functions always return a promise. No code change needed, only the version.

The fix if you are stuck on Express 4

A small wrapper that hands rejections to next:

const wrap = (fn) => (req, res, next) =>
  Promise.resolve(fn(req, res, next)).catch(next);

app.get('/async', wrap(async () => {
  await sleep(10);
  throw new Error('async boom');
}));

Run on Express 4.22.3 with Sentry initialised:

wrapped express4: http=500 time=0.029606s
SINK event: Error async boom mech= auto.middleware.express

500 in about 30 ms, and the event now comes through the Express error handler, same as the sync case. Sentry's setupExpressErrorHandler has to go after your routes and before your own error middleware, which is where it was in my app.js.

What I would check in your app today

Which Express version are you on? npm ls express. If it says 4.x, every async handler without a catch is a hang waiting for a bad day.
Grep for handlers that look safe but are not. app.get('/x', async (req, res) => { with no try and no wrapper. Also setTimeout and event emitter callbacks, which Express never sees on any version. The Express docs say to catch those yourself and call next(err).
Look at the error source in your tracker. In my run the hung request showed up as an unhandled rejection, not as an Express error. If your tracker has a mechanism or "handled" field, filter for the unhandled rejection ones. Those are the routes without a wrapper.
Add a response timeout in front of the app. I did not benchmark this, so I will not give you a number. The point is that a hung request should end with a 504 from your proxy in seconds, not a user closing the tab.
Do not turn off the crash to make the noise stop. Crashing was the better failure mode in Run 1. A restart loop is easier to spot than a silent hang.

Where I run this

I build Epure, a small self-hosted error tracker: one Rust binary and Postgres 16, errors only, and you point the official Sentry SDK at it by swapping the DSN. The results above come from the throwaway sink, not from Epure, so they say nothing about it either way. If you want to see what that DSN swap looks like, the docs have it.

What this does not show

One Node version (20.19.2), one SDK version. A different @sentry/node major or Node's --unhandled-rejections flag could change the hang.
A single route, tested with curl. I did not run a real database or a proxy in front.
I read the Express 5 behaviour from the docs and confirmed it with the run above. I did not read the router source.

Which Express version is your production API on right now, and does it have a request timeout in front of it?

Your .env hit git. Here's how I keep secrets on a VPS

Amorizz — Thu, 15 Oct 2026 13:31:31 +0000

I pushed a small Node + Postgres Compose stack to a private repo and only then noticed .env was in the first commit. DATABASE_URL had a real password. Adding .gitignore afterward did nothing useful: Git still had the blob, and git check-ignore stayed quiet while the path was tracked.

This is the layout I use on a VPS now. Everything below was run on the box on 2026-10-15 with git 2.47.3, Docker Engine 26.1.5, Compose 2.26.1 and Node 20. Numbers and command output are from those runs.

TL;DR

Put .env in .gitignore before the first commit. Commit .env.example with fake values. If .env already landed in git, git rm --cached only stops future commits. The old blob stays until you rewrite history or rotate the secret.
On the VPS, keep real secrets in a file mode 600 (for example secrets.env) and point Compose at it with env_file. Do not put ${POSTGRES_PASSWORD} in the YAML if that value comes from a project .env you might commit.
Compose interpolates ${...} in the Compose file itself, including inside command: strings. A JS template literal like `token=${t}` becomes empty before the container starts. Prefer a script file, or write $$t.

What are you actually protecting?

Three different places can hold the same password. Fixing one does not fix the others.

Place	What goes wrong	What fixes it
Git history	Clone, fork, or a future public flip exposes the blob forever	Never commit it; if you did, rotate and treat history as burned
File on the VPS	Any local account can read a `644` secrets file	`chmod 600`, owner = the deploy user
Process environment	`docker compose config`, crash dumps, child processes	Prefer `env_file`; avoid baking secrets into resolved YAML via `${}`

.gitignore only affects the first column, and only for paths that are not already tracked.

How does .env end up in git?

I reproduced the failure in a throwaway repo. First commit included .env. Then I added:

.env
.env.*
!.env.example

After that commit, Git still listed .env:

$ git check-ignore -v .env
# (no output: still tracked, so ignore rules do not apply)

$ git ls-files | grep env
.env
.env.example

$ git show "$(git rev-list --max-parents=0 HEAD):.env" | head -3
DATABASE_URL=postgres://app:[REDACTED]@db:5432/app
EPURE_DSN=https://[REDACTED]@ingest.example.com/1
NODE_ENV=production

git rm --cached .env plus a new commit makes check-ignore work again:

$ git rm --cached .env
$ git commit -m "stop tracking .env (too late for history)"
$ git check-ignore -v .env
.gitignore:1:.env   .env

The first commit still has the file. git rev-list --objects --all still showed the .env blob. Ignore files are not a time machine.

The correct order is boring and it works. Create .gitignore and .env.example first, then add:

$ git status --short
A  .env.example
A  .gitignore
A  app.js
# .env is absent from the index

$ git check-ignore -v .env
.gitignore:1:.env   .env

$ git ls-files
.env.example
.gitignore
app.js

No secret string in git grep across $(git rev-list --all).

What goes on the VPS?

I keep two files next to the Compose project:

.env.example in git: keys and fake values, so a teammate knows what to create.
secrets.env on the host only: real values, mode 600, listed in .gitignore.

$ chmod 600 secrets.env
$ stat -c '%a %n' secrets.env .env.worldreadable
600 secrets.env
644 .env.worldreadable

On the lab box, Python reported other_read=False for 600 and other_read=True for 644. Same owner can read both. Every other account on the VPS can read the 644 copy.

A minimal systemd unit can load the same file:

[Service]
WorkingDirectory=/opt/app
EnvironmentFile=/etc/app/secrets.env
ExecStart=/usr/bin/node /opt/app/server.js

Same rule: /etc/app/secrets.env is 600, not in git.

Compose: env_file vs ${PASSWORD} in the YAML

Compose loads a project .env for interpolation in the Compose file. That is separate from what the container sees as process.env.

Bad shape (host .env supplies ${POSTGRES_PASSWORD}, and the resolved config prints it):

# compose.bad.yml
services:
  db:
    image: postgres:16.15-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: app
  app:
    image: node:22.23.3-alpine
    environment:
      DATABASE_URL: postgres://app:${POSTGRES_PASSWORD}@db:5432/app
      APP_SECRET: ${APP_SECRET}

$ docker compose -f compose.bad.yml config | grep -E 'PASSWORD|DATABASE_URL|APP_SECRET'
      APP_SECRET: from-host-dotenv
      DATABASE_URL: postgres://app:HostInterpolatedSecret@db:5432/app
      POSTGRES_PASSWORD: HostInterpolatedSecret

That was 2 plaintext hits for HostInterpolatedSecret in the full config dump. Fine for local debugging. Bad to paste into an issue, a CI log, or a screenshot.

Better shape: put secrets in secrets.env, mount them with env_file, and keep the YAML free of ${SECRET}:

# compose.yml
services:
  db:
    image: postgres:16.15-alpine
    env_file:
      - secrets.env
    environment:
      POSTGRES_USER: app
      POSTGRES_DB: app
      # POSTGRES_PASSWORD comes from secrets.env

  app:
    image: node:22.23.3-alpine
    working_dir: /app
    volumes:
      - ./print-env.js:/app/print-env.js:ro
    env_file:
      - secrets.env
    environment:
      POSTGRES_USER: app
      POSTGRES_HOST: db
      POSTGRES_DB: app
    command: ["node", "print-env.js"]

// print-env.js
const u = process.env.POSTGRES_USER;
const p = process.env.POSTGRES_PASSWORD;
const h = process.env.POSTGRES_HOST;
const d = process.env.POSTGRES_DB;
console.log("password_in_process_env", Boolean(p));
console.log("password_len", (p || "").length);
console.log("password_equals_envfile", p === "EnvFileOnlySecret");

With the project .env renamed away so only secrets.env could supply the password:

$ docker compose -f compose.better.yml run --rm --no-deps app
password_in_process_env true
password_len 17
NODE_ENV production
password_equals_envfile true
password_equals_host_dotenv false

password_len 17 matches EnvFileOnlySecret. The host-interpolated value never appeared.

The ${} gotcha inside command: strings

I put a JS template literal in the Compose command once. Compose warned and emptied it:

level=warning msg="The \"t\" variable is not set. Defaulting to a blank string."

Resolved command became console.log('template', \token=); with no t. The container never saw ${t}. Fix: move the script to a file (as above), or escape as $$t in the YAML so Compose emits a literal $t for the shell or Node source.

Failure checklist

.gitignore after the first commit. Tracked paths ignore the ignore file. Run git ls-files .env and git check-ignore -v .env.
git rm --cached without rotating. Future commits are clean. Clones of the old history still have the password.
.env.example missing or filled with real values. People copy the wrong file. Keep fake placeholders only.
Mode 644 on the VPS secrets file. Any local account can read it. Use 600.
${POSTGRES_PASSWORD} in Compose YAML. docker compose config prints the value. Prefer env_file and build URLs inside the app from separate env vars.
JS ${...} inside Compose command:. Compose eats it. Use a file or $$.
Assuming a private GitHub repo is enough. Private today can be public tomorrow, or the laptop backup can leak. History still carries the blob.
Committing secrets.env "just for the team". That is the same bug with a different filename. Use a password manager, sealed secrets, or a one-time scp onto the VPS.

Where this shows up for me

The stack I'm building, Epure, is a two-container Compose file (Rust binary + Postgres 16) for exception-only error monitoring. Same rule as above: example env in git, real DSN and DB password only on the host. The product is not APM, replay, or logs. If you self-host it, the docs assume you already keep secrets out of the repo.

After you stop tracking .env, do you rotate the leaked secret, or only fix the ignore file?

Write a Docker Compose healthcheck that actually checks your app

Amorizz — Sun, 11 Oct 2026 13:40:44 +0000

I wrote what looked like a careful Compose file for a small Node + Postgres app: a pg_isready healthcheck on Postgres and depends_on: condition: service_healthy on the app. On a fresh volume the app died with ECONNREFUSED while docker compose ps showed the database as (healthy).

Then I stopped Postgres to see what my readiness endpoint would say, and the Node process crashed instead. Six restarts in 40 seconds. Both bugs came from the same mistake: I was checking that something was running, not that it could do its job.

This is the setup I ended up with. Everything below was run on Docker Engine 26.1 with Compose 2.26, postgres:16.15-alpine and node:22.23.3-alpine, and the outputs are pasted from those runs, trimmed to the relevant lines (ps cut down to the SERVICE and STATUS columns, Start/End timestamps dropped from inspect).

TL;DR

pg_isready with no -h talks to the Unix socket, and during first-boot init the official Postgres image runs a temporary server that only listens on that socket. Add -h 127.0.0.1 so the check uses TCP like your app does.
Split your app's probes: /healthz answers "is the process alive", /readyz answers "can I serve a real request right now" (boot finished, database answers SELECT 1 within 1 second).
Plain Docker never restarts a container for being unhealthy. Pick what the healthcheck probes based on what reacts to it in your setup.

What does a healthcheck actually prove?

A healthcheck proves only what its command touches. "Process up", "port open", "app booted" and "dependencies reachable" are four different facts, and most Compose files check the first or second one and assume the rest.

Check	What it proves	What it misses
Container is `Up`	PID 1 hasn't exited	Everything else
Port accepts a TCP connection	Something is listening	App may still be booting, DB may be down
`pg_isready` (socket)	A Postgres server answers on the socket	First-boot temp server, TCP, auth, your database
`GET /healthz` returns 200	Event loop runs, HTTP stack works	Database, migrations, config
`GET /readyz` returns 200	Boot finished and the DB answered `SELECT 1` in 1s	Slow queries, other dependencies you didn't add

Kubernetes splits this into liveness and readiness probes. Docker gives you one healthcheck per container, so you have to decide which question it answers.

Why did pg_isready say healthy too early?

Because it asked the wrong server. The official image's entrypoint runs initdb, starts a temporary Postgres that listens only on the Unix socket, runs your /docker-entrypoint-initdb.d scripts, then shuts it down and starts the real server on TCP. pg_isready -U app uses the socket by default, so it reports "accepting connections" while the temp server is up.

My repro has a slow init script (an 8 second sleep standing in for a schema load):

#!/bin/sh
# initdb/01-slow-init.sh: stands in for a first boot that does real work
echo "init: loading schema (slow on purpose)"
sleep 8
psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "CREATE ROLE reporting NOLOGIN;"

And a Compose file that trusts plain pg_isready:

# compose.lie.yml: the version that lies
services:
  db:
    image: postgres:16.15-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    volumes:
      - ./initdb:/docker-entrypoint-initdb.d:ro
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "app"]
      interval: 1s
      timeout: 3s
      retries: 30
  app:
    build: ./app
    environment:
      DATABASE_URL: postgres://app:app@db:5432/app
    depends_on:
      db:
        condition: service_healthy

$ docker compose -f compose.lie.yml up -d
$ docker compose -f compose.lie.yml ps -a
SERVICE   STATUS
app       Exited (1) 3 seconds ago
db        Up 5 seconds (healthy)
$ docker inspect --format '{{json .State.Health}}' lab-2026-10-11-healthcheck-db-1
{"Status": "healthy", "FailingStreak": 0, "Log": [{"ExitCode": 0, "Output": "/var/run/postgresql:5432 - accepting connections\n"}]}

Look at the Output: /var/run/postgresql:5432. That's the socket. The logs show the order (timestamps trimmed):

db-1   13:23:59.918  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
db-1   13:24:00.056  init: loading schema (slow on purpose)
app-1  13:24:00.901  listening on :3000
app-1  13:24:00.904  boot failed: ECONNREFUSED
db-1   13:24:08.065  CREATE ROLE
db-1   13:24:08.190  listening on IPv4 address "0.0.0.0", port 5432

The app gave up about 7 seconds before Postgres listened on TCP. Adding psql -c 'SELECT 1' over the socket doesn't fix it either. I tried: the temp server answers that too, and the app still got ECONNREFUSED. The fix is to probe the way your app connects, over TCP.

The Compose file that tells the truth

Probe Postgres over TCP, give the app its own healthcheck against /readyz, and gate startup on both. This is the full file.

# compose.yml
services:
  db:
    image: postgres:16.15-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    volumes:
      - ./initdb:/docker-entrypoint-initdb.d:ro
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      # -h 127.0.0.1 forces TCP. The first-boot temp server only listens on the socket.
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U app -d app && psql -h 127.0.0.1 -U app -d app -tAc 'SELECT 1' | grep -q 1"]
      interval: 5s
      timeout: 3s
      retries: 5
      start_period: 30s
      start_interval: 1s

  app:
    build: ./app
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://app:app@db:5432/app
    ports:
      - "127.0.0.1:3000:3000"
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/readyz').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 20s
      start_interval: 1s
    depends_on:
      db:
        condition: service_healthy
        restart: true

volumes:
  pgdata:

What each knob does:

start_period: failures in this window don't count toward retries, but the first success marks the container healthy right away. Size it for your slowest cold boot.
start_interval (Engine 25+): how often to probe during start_period. 1s here means up --wait returns as soon as things are ready instead of waiting out a 10s interval.
timeout: kept above the app's own 1s DB timeout, so /readyz returns a clean 503 before Docker kills the probe.
restart: true under depends_on: Compose restarts the app when you restart db with a Compose command. It doesn't fire when the container runtime restarts a crashed db.

The /healthz and /readyz handlers

/healthz should be cheap and depend on nothing, so it only fails when the process itself is broken. /readyz should fail fast when the app can't serve a real request: boot not finished, or the database not answering within a second.

{ "name": "health-lab", "private": true, "dependencies": { "pg": "8.13.1" } }

// server.js: /healthz says "the process works", /readyz says "I can do real work"
const http = require("node:http");
const { Pool } = require("pg");

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 5,
  connectionTimeoutMillis: 1000, // a hung DB must fail the probe, not hang it
});

// Without this, a DB restart kills the whole process (unhandled 'error' event).
pool.on("error", (err) => console.error("pg idle client error:", err.code || err.message));

let booted = false; // flips after startup work (migrations, caches) is done

async function boot() {
  await pool.query("CREATE TABLE IF NOT EXISTS hits (id serial PRIMARY KEY, at timestamptz DEFAULT now())");
  booted = true;
  console.log("boot: migrations done");
}

function send(res, code, body) {
  res.writeHead(code, { "content-type": "application/json" });
  res.end(JSON.stringify(body));
}

const server = http.createServer(async (req, res) => {
  if (req.url === "/healthz") return send(res, 200, { status: "ok" });

  if (req.url === "/readyz") {
    if (!booted) return send(res, 503, { status: "starting" });
    try {
      await pool.query({ text: "SELECT 1", query_timeout: 1000 });
      return send(res, 200, { status: "ready", db: "ok" });
    } catch (err) {
      return send(res, 503, { status: "not_ready", db: err.code || err.message });
    }
  }

  try {
    await pool.query("INSERT INTO hits DEFAULT VALUES");
    send(res, 200, { hello: "world" });
  } catch (err) {
    send(res, 500, { error: err.code || err.message });
  }
});

server.listen(3000, "0.0.0.0", () => console.log("listening on :3000"));

// Retry boot instead of exiting: stay live (/healthz 200), report not ready (/readyz 503).
(async function bootLoop() {
  for (let attempt = 1; !booted; attempt++) {
    try {
      await boot();
    } catch (err) {
      console.error(`boot attempt ${attempt} failed: ${err.code || err.message}`);
      await new Promise((r) => setTimeout(r, Math.min(1000 * attempt, 10000)));
    }
  }
})();

FROM node:22.23.3-alpine
WORKDIR /app
COPY package.json ./
RUN npm install --omit=dev --no-audit --no-fund
COPY server.js ./
USER node
CMD ["node", "server.js"]

My first version had neither the pool.on("error") line nor the retry loop. When I stopped Postgres, pg emitted 57P01 terminating connection due to administrator command on an idle client, nothing listened for it, and Node exited. The restart policy brought it back, boot failed because the DB was still down, it exited again: RestartCount was 6 after 40 seconds.

Check it: start, then break the database

Run it with --wait so the command only returns once every healthcheck passes. Then stop and pause Postgres and watch what each probe says.

$ time docker compose up -d --build --wait
 Container lab-2026-10-11-healthcheck-db-1  Healthy
 Container lab-2026-10-11-healthcheck-app-1  Healthy
real    0m14.674s

$ docker compose ps
SERVICE   STATUS
app       Up 1 second (healthy)
db        Up 11 seconds (healthy)

$ docker inspect --format '{{json .State.Health}}' lab-2026-10-11-healthcheck-db-1
{"Status": "healthy", "FailingStreak": 0, "Log": [{"ExitCode": 0, "Output": "127.0.0.1:5432 - accepting connections\n"}]}

$ curl -s localhost:3000/healthz; curl -s localhost:3000/readyz
{"status":"ok"}
{"status":"ready","db":"ok"}

The inspect output now says 127.0.0.1:5432, so the check went over TCP. Now take the database away:

$ docker compose stop db
$ curl -s -w ' HTTP %{http_code}\n' localhost:3000/healthz
{"status":"ok"} HTTP 200
$ curl -s -w ' HTTP %{http_code}\n' localhost:3000/readyz
{"status":"not_ready","db":"Connection terminated due to connection timeout"} HTTP 503

# 40 seconds later
$ docker compose ps -a
SERVICE   STATUS
app       Up 43 seconds (unhealthy)
db        Exited (0) 42 seconds ago
$ docker inspect --format '{{.RestartCount}} {{.State.Health.Status}}' lab-2026-10-11-healthcheck-app-1
0 unhealthy

That 0 unhealthy is the line most people don't expect. restart: unless-stopped reacts to the process exiting. It ignores health. A hung database is a different failure from a stopped one, so pause it too:

$ docker compose start db     # app goes back to (healthy) on its own
$ docker compose pause db
$ time curl -s -w ' HTTP %{http_code}\n' localhost:3000/readyz
{"status":"not_ready","db":"Query read timeout"} HTTP 503
real    0m1.012s

One second and a 503, instead of a probe that hangs until Docker's timeout.

Should the Docker healthcheck call /healthz or /readyz?

It depends on what reacts to unhealthy in your setup. If nothing restarts unhealthy containers, point it at /readyz so depends_on and up --wait mean "ready to serve". If something does restart them, point it at /healthz, or a database blip turns into every app container restarting at once.

What reacts to `unhealthy`	Point the healthcheck at	Why
Nothing (plain Compose, `restart:` policy only)	`/readyz`	Gates `depends_on` and `up --wait` on real readiness, restarts nothing
Swarm, or an autoheal-style sidecar	`/healthz`	A DB outage shouldn't restart healthy app processes
Reverse proxy health checks (Traefik, Caddy, a load balancer)	`/readyz` from the proxy	Pull traffic from a replica that can't serve
Deploy script after `docker compose pull`	`/readyz` with `curl -f`	Fail the deploy before you switch traffic

Failure checklist

When the status and reality disagree, it's usually one of these. I reproduced 1 through 5 and 7 in the lab above.

pg_isready with no -h. It checks the socket, so it passes during first-boot init. Use -h 127.0.0.1.
curl isn't in the image. node:22.23.3-slim ships neither curl nor wget, and the check fails with exec: "curl": executable file not found in $PATH. Use node -e "fetch(...)", or busybox wget on Alpine.
One string in exec form. ["CMD", "pg_isready -U postgres"] makes Docker look for a binary literally named pg_isready -U postgres. Split the arguments, or use CMD-SHELL when you need && or pipes.
localhost resolves to ::1. In the Alpine container, localhost resolved to ::1. My test server listened on 0.0.0.0 (IPv4 only), and wget http://localhost:3000/ got Connection refused. Use 127.0.0.1.
No pool.on("error") in Node. A Postgres restart kills the process with an unhandled 'error' event, and the restart loop hides it.
/readyz with no timeout. Without connectionTimeoutMillis and query_timeout, a hung DB makes the probe wait until Docker kills it, and the health log only says Health check exceeded timeout (3s). Time out inside the app, below the healthcheck timeout.
Expecting unhealthy to restart anything. It doesn't, in plain Docker. It only feeds depends_on, --wait, docker ps and whatever tool you add.
$ in a CMD-SHELL string. Compose interpolates $VAR before the shell sees it. Write $$POSTGRES_USER if you want the container's env var.

Where this runs for me

The stack I'm building, Epure, is a two-container Compose file: one Rust binary and Postgres 16. It does exception-only error monitoring for apps that already use the official Sentry SDKs, no APM, replay or logs. Its production checklist has the same lesson in another form: /health returns ok over plain HTTP while login loops, because the session cookie is HTTPS-only. A green probe only tells you the process answered.

The lab is small enough to copy: compose.yml, server.js, package.json, the Dockerfile above, and one init script with a sleep 8 in it if you want to see the first-boot race yourself.

What does your /readyz check besides the database?

Your sampleRate won't save you from an error flood. Here's what does

Amorizz — Wed, 07 Oct 2026 20:21:45 +0000

I wrote a flood test for the error tracker I'm building: one bug thrown 997 times in a retry loop, plus three rare bugs thrown once each. In the run that looked most like production, all three rare bugs vanished before they left the Node process.

Then I tried the fix everyone reaches for, sampleRate: 0.1. Across five runs, 2 of the 15 rare errors made it. The loop that caused the mess was still the biggest thing on the screen.

TL;DR

sampleRate drops errors at random. It cuts the noisy loop by 90% and your one-off bugs by the same 90%, so the error you needed is the one most likely to disappear.
The SDK drops events before sampling even runs: Dedupe eats exact repeats, and a tight burst overflows the 64-slot transport buffer.
What worked: send everything, then rate limit stored bodies per fingerprint on the server. Count 100% of hits, keep the first 100 stack traces per bug per minute, let every new bug through.

Why doesn't sampleRate fix an error flood?

Because it doesn't know which error is the flood. sampleRate is a per-event coin flip in the SDK. At 0.1, every error has a 10% chance of being sent, whether it's the 900th copy of the same TypeError or the only RangeError you'll see all week.

That's fine for volume and bad for signal. A bug that fires once has a 90% chance of never reaching you. The count you do see is off by about 10x, because the server gets roughly 100 events and nothing in them says "multiply me". Client reports tell the server how many events were dropped and why (sample_rate, queue_overflow), but not which bug they belonged to.

The flood lab: one loop, three rare bugs

You can reproduce this in a few minutes with Node 20.19 or newer. No Docker, no account. ingest.js is a fake endpoint that parses just enough of the Sentry envelope format to count errors per fingerprint. flood.js uses the real @sentry/node SDK.

mkdir flood-lab && cd flood-lab
npm init -y >/dev/null
npm i @sentry/node@11.5.0 --save-exact

ingest.js. The fingerprint is the exception type plus the top in-app frame (file, function, line). The valve is a token bucket per fingerprint: 100 tokens, refilled at 100 per minute.

// ingest.js: fake error ingest with a per-fingerprint spike valve
const http = require("node:http");
const zlib = require("node:zlib");
const crypto = require("node:crypto");

const VALVE = process.env.VALVE !== "off";
const RATE = 100; // stored bodies per fingerprint per minute
const buckets = new Map();
const issues = new Map();

function allowStore(fp) {
  const now = Date.now();
  const b = buckets.get(fp) ?? { tokens: RATE, last: now };
  b.tokens = Math.min(RATE, b.tokens + ((now - b.last) / 60000) * RATE);
  b.last = now;
  buckets.set(fp, b);
  if (b.tokens >= 1) { b.tokens -= 1; return true; }
  return false;
}

function fingerprint(event) {
  const ex = event.exception?.values?.at(-1) ?? {};
  const frames = ex.stacktrace?.frames ?? [];
  const top = frames.filter((f) => f.in_app).at(-1) ?? frames.at(-1) ?? {};
  const key = `${ex.type}\0${top.filename}:${top.function}:${top.lineno}`;
  const fp = crypto.createHash("sha256").update(key).digest("hex");
  return { fp, title: `${ex.type}: ${ex.value}` };
}

http.createServer((req, res) => {
  if (req.url === "/stats") return res.end(JSON.stringify([...issues.values()]));
  const chunks = [];
  req.on("data", (c) => chunks.push(c));
  req.on("end", () => {
    let body = Buffer.concat(chunks);
    if (req.headers["content-encoding"] === "gzip") body = zlib.gunzipSync(body);
    const lines = body.toString("utf8").split("\n");
    for (let i = 1; i + 1 < lines.length; i += 2) {
      if (JSON.parse(lines[i]).type !== "event") continue;
      const { fp, title } = fingerprint(JSON.parse(lines[i + 1]));
      const issue = issues.get(fp) ?? { title, count: 0, stored: 0 };
      issue.count += 1;                                // every hit is counted
      if (!VALVE || allowStore(fp)) issue.stored += 1; // bodies are rationed
      issues.set(fp, issue);
    }
    res.statusCode = 202; // the client never sees the valve
    res.end("{}");
  });
}).listen(9000, () => console.log(`ingest on :9000 (valve ${VALVE ? "on" : "off"})`));

flood.js. Three env switches: SAMPLE_RATE, DEDUPE=off and PACE=off.

// flood.js: one bug stuck in a retry loop, plus three rare bugs you care about
const Sentry = require("@sentry/node");

const SAMPLE_RATE = Number(process.env.SAMPLE_RATE ?? 1);
const DEDUPE = process.env.DEDUPE !== "off";
const PACE = process.env.PACE !== "off";

Sentry.init({
  dsn: "http://public@localhost:9000/1",
  sampleRate: SAMPLE_RATE,
  tracesSampleRate: 0,
  integrations: (defaults) =>
    DEDUPE ? defaults : defaults.filter((i) => i.name !== "Dedupe"),
});

function chargeCard() { throw new TypeError("Cannot read properties of undefined (reading 'id')"); }
function applyCoupon() { throw new RangeError("discount out of range: -5"); }
function sendReceipt() { throw new Error("SMTP 421 try again later"); }
function exportCsv() { throw new SyntaxError("Unexpected token < in JSON"); }

const rare = { 250: applyCoupon, 500: sendReceipt, 750: exportCsv };

(async () => {
  for (let i = 1; i <= 1000; i++) {
    try { (rare[i] ?? chargeCard)(); } catch (e) { Sentry.captureException(e); }
    if (PACE && i % 50 === 0) await Sentry.flush(2000);
  }
  await Sentry.flush(5000);
  const issues = await (await fetch("http://localhost:9000/stats")).json();
  console.log(`sampleRate=${SAMPLE_RATE} dedupe=${DEDUPE ? "on" : "off"} pace=${PACE ? "on" : "off"}`);
  console.log("issue".padEnd(36), "count".padStart(6), "stored".padStart(7));
  for (const { title, count, stored } of issues) {
    console.log(title.slice(0, 36).padEnd(36), String(count).padStart(6), String(stored).padStart(7));
  }
})();

Run the ingest in one terminal and the flood in another. The ingest keeps state in memory, so restart it between runs.

# terminal 1
VALVE=off node ingest.js

# terminal 2
PACE=off node flood.js

Run 1: the SDK drops more than you think

Before any sampling, the SDK already throws events away. Here's the naive run: defaults, no pacing, valve off.

sampleRate=1 dedupe=on pace=off
issue                                 count  stored
TypeError: Cannot read properties of      4       4
RangeError: discount out of range: -      1       1
Error: SMTP 421 try again later           1       1
SyntaxError: Unexpected token < in J      1       1

997 TypeErrors thrown, 4 received. That's dedupeIntegration, on by default. It compares each event with the previous one and drops exact repeats, so you get one TypeError per stretch between the rare errors. With debug: true you'll see this 993 times:

Sentry Logger [warn]: Event dropped due to being a duplicate of previously captured event.

Real floods come from many browsers or workers, each with its own "previous event". So I turned Dedupe off:

PACE=off DEDUPE=off node flood.js

sampleRate=1 dedupe=off pace=off
issue                                 count  stored
TypeError: Cannot read properties of     64      64

This is the run that bit me. 64 events arrived and all three rare bugs were gone. The transport allows 64 requests in flight (DEFAULT_TRANSPORT_BUFFER_SIZE = 64 in @sentry/core). A synchronous burst fills it and everything after is dropped. With debug: true, 936 times:

Sentry Logger [log]: Recording outcome: "queue_overflow:error"

The rare bugs were events 250, 500 and 750. They never had a chance.

In the lab, pacing with await Sentry.flush() every 50 events fixes it, and so does transportOptions: { bufferSize: 2000 }. Both gave me 997 + 1 + 1 + 1. In a real incident, a bigger buffer just means you're queueing the flood in your app's memory.

Run 2: sampleRate 0.1 loses the rare bugs

Now the popular fix. Paced, Dedupe off, valve off, sampleRate at 0.1, five runs:

DEDUPE=off SAMPLE_RATE=0.1 node flood.js

sampleRate=0.1 dedupe=off pace=on
issue                                 count  stored
TypeError: Cannot read properties of    120     120
SyntaxError: Unexpected token < in J      1       1

That was one of my two lucky runs: one rare bug out of three. The other lucky run caught the SMTP error instead. The remaining three runs got 96, 102 and 85 TypeErrors and zero rare bugs. Yours will differ, it's random. That's the point.

	Loop bug (thrown 997x)	Rare bugs (3 per run)
Arrived over 5 runs	85 to 120 per run	2 of 15
What you conclude	count is off by about 10x	most of them never happened

The loop still owns the issue list. The bugs you'd want to look at are the ones that disappeared.

Run 3: count everything, ration the bodies

Same flood, no sampling, valve on.

# terminal 1
node ingest.js

# terminal 2
DEDUPE=off node flood.js

sampleRate=1 dedupe=off pace=on
issue                                 count  stored
TypeError: Cannot read properties of    997     100
RangeError: discount out of range: -      1       1
Error: SMTP 421 try again later           1       1
SyntaxError: Unexpected token < in J      1       1

Three runs, same output each time. The count is exact. The loop bug keeps 100 full stack traces and the rest are counted, not stored. Each rare bug gets its own bucket with 100 fresh tokens, so it always lands.

Every request got a 202, so the SDK has no reason to back off. All the throttling happens where you can see it: on the server, per bug.

How the spike valve works in Epure

Same idea, in Rust. Epure is the self-hosted error tracker I'm building. It takes errors from the official Sentry SDKs through a DSN swap and drops transactions and replays. Here's the core of the valve from crates/server/src/pipeline/spike.rs, trimmed:

const DEFAULT_RATE_PER_MINUTE: f64 = 100.0;

pub enum SpikeDecision { AllowStore, CounterOnly }

impl TokenBucket {
    fn check(&mut self) -> SpikeDecision {
        self.refill();
        if self.tokens >= 1.0 {
            self.tokens -= 1.0;
            SpikeDecision::AllowStore
        } else {
            SpikeDecision::CounterOnly
        }
    }
}

AllowStore queues the full event. CounterOnly queues a job that only bumps the issue counter. Buckets sit in a DashMap keyed by fingerprint, and idle ones get evicted once there are 20k keys. The fingerprint is a SHA-256 of the exception type plus the top in-app frame, unless the SDK sends a custom fingerprint.

From the outside, per the errors and rate limits docs:

Mechanism	Default	What the client sees
Spike valve	100 raw events / minute / fingerprint	`202`. Extra bodies aren't stored, the counter still goes up.
Project ingest cap	5000 events / hour / project	`403` `ingest_cap_exceeded`

No Redis. The buckets live in memory in the Rust process, next to Postgres 16, in a two-container compose file. The repo has an integration test that posts the same browser envelope 150 times and expects 150 202s, at least 150 counter increments and at most 100 stored rows.

Why not a project-level limit?

Project-level limits have the same blind spot as sampleRate. They protect the bill and can't tell which bug matters.

Sentry's SaaS has Spike Protection. Per its docs, it sets a per-project hourly threshold from your quota and the last 7 days of traffic, then discards events above it. That's a real safety net for your quota. But it limits the project, so a rare bug that lands mid-spike competes with the loop for the same allowance.

Epure doesn't dodge this either. Its hourly project cap is checked before the valve, and counter-only hits count toward it. Rough math: a loop sustained above about 83 events a minute (5000 / 60) burns the default cap within the hour. After that, every event from the project gets a 403 until the next clock hour, rare bugs included. You can raise the cap per project. The valve keeps a loop out of your database. It doesn't stop a sustained loop from eating the cap.

When is sampleRate still the right call?

When the upload itself costs you (a browser SDK on a lot of phones), or when your vendor bills per event and you need a ceiling today.

If one known error is the noise, an ignoreErrors entry or a beforeSend filter for that exact error beats a global coin flip. And don't mix up the knobs: tracesSampleRate is performance data, sampleRate is errors. Turning down traces is cheap. Turning down errors is how you lose the one-off bug.

Failure checklist

If your flood test doesn't match the outputs above:

Only a handful of events arrived. Dedupe is on by default. Filter it out or interleave different errors.
Exactly 64 events arrived. You hit the transport buffer. Pace with await Sentry.flush() or set transportOptions: { bufferSize }.
Rare errors got merged into the loop issue. Your fingerprint is too coarse. Group by message only and every Cannot read properties of undefined shares one bucket.
A deploy reset your throttling. Buckets are in memory, so a restart refills them. And since the frame key includes the line number, moving code gives the bug a new fingerprint.
You run several ingest processes. In-memory buckets are per process. Two processes can store up to 2x the bodies per minute.
Everything returns 403 ingest_cap_exceeded. That's the hourly project cap. The valve never returns an error.
202 but the issue list is empty. Accept is async, so the event may still be queued. Check the DSN's project and environment, then docker compose logs epure.
Fewer events than expected, no errors anywhere. Someone left sampleRate below 1 in shared config: grep -rn "sampleRate" src/.

What would you set?

I picked 100 stored stack traces per bug per minute because that's about what I'd scroll through during an incident, and I'm not sure it's right. If a loop hit your app tonight, how many full stack traces of the same bug per minute would you actually want kept?

Why Rust + Postgres RLS

Amorizz — Sun, 04 Oct 2026 13:20:31 +0000

TL;DR

We wanted multi-tenant exception ingest on a two-container stack: one Rust binary + PostgreSQL 16. No Redis. No Kafka.
Dashboard reads go through Postgres RLS with SET LOCAL app.current_org_id. App bugs must not cross orgs on a shared DB.
Ingest is DSN → project_id, not the app RLS role. RLS is defense-in-depth for dashboard /api/v1, not magic on every path.

I build Epure: exception-only error monitoring you can self-host. This week I am writing down the stack bet, not a migrate recipe. We already shipped the cheap VPS shape and the DSN swap. The question people ask next is why Rust plus Postgres row-level security instead of a bigger fleet or app-only filters.

Why Rust + Postgres RLS for exception ingest?

We optimized for a small blast radius on a shared Postgres: org-scoped dashboard reads enforced in the database, ingest scoped by DSN, two containers total.

Tenancy on a side-project VPS is easy to hand-wave. One engineer, one DB, WHERE org_id = ? in every handler. That works until a handler forgets the filter, a join leaks a neighbor row, or a reporting query skips the org check. On a multi-tenant exception store that is the whole product surface: other people's stack traces.

So we put the tenant key in Postgres. The dashboard role cannot see another org's rows even when application code is wrong. Rust keeps the binary one process: ingest HTTP, migrations, dashboard API. Postgres 16 holds events, issues, and the RLS policies. That is the whole product runtime besides your TLS edge.

If you run GlitchTip or self-hosted Sentry, the portable lesson is the same: decide where the tenant boundary lives before you scale the number of tenants on one database.

Threat model: who can read what if X fails?

Cookie and membership checks gate the dashboard. RLS is the backstop if a query forgets the org filter. Ingest trusts the DSN, not a client-supplied org id.

Failure	Without RLS (app filters only)	With `epure_app` + RLS
Handler drops `WHERE org_id = …`	Neighbor org rows can return	Policy still filters on `app.current_org_id`
Client sends another org's UUID	App must reject; easy to miss on one route	Session sets org from membership, not from the body
Stolen session cookie for Org A	Sees Org A (expected)	Still only Org A; no cross-org via forgotten filter
Leaked ingest DSN for Project P	Writes land on P	Same: ingest is DSN-scoped; not the app RLS role
Dashboard uses migrate/`epure` role by mistake	Full table access	Wrong. `epure` is for migrations. App must use `epure_app`

What we are not claiming: RLS stops a stolen DSN, a stolen cookie inside the right org, or a bug in the ingest writer. Different paths, different trust boundaries.

Why not a shared DB without RLS, app-only filters, or a heavier stack?

App-only filters fail open on one missed query. Heavier stacks buy isolation with ops cost we refused on a two-container box.

Option	Why it lost for this job
Shared DB, no RLS	Every read path must remember the org filter. One miss is a tenancy bug.
App-only org filters	Fine for a prototype. Weak as the only line when exceptions are the payload.
Separate database per customer	Strong isolation. Painful backups, migrations, and $5-class ops.
Full self-hosted Sentry (~65 containers)	Real product. Wrong unit when you only need exceptions ($5 VPS notes).
Redis / Kafka / extra workers	Useful for big fleets. We did not want them for exception ingest on one VPS.

GlitchTip is a fair lighter alternative on Django-shaped stacks. We still chose Rust + Postgres RLS because we are building the ingest path and want the tenant boundary in the database for dashboard reads. A GlitchTip reader can still steal the role split and SET LOCAL pattern below.

Working sketch: three roles, SET LOCAL, policy shape

Three Postgres roles on one epure database. Dashboard: cookie → membership → SET LOCAL app.current_org_id → queries. Ingest: DSN → project_id. Migrations: epure only.

Role / URL	Job
`epure` via `DATABASE_URL`	Migrations / bootstrap on startup
`epure_ingest` via `EPURE_INGEST_DATABASE_URL`	DSN-scoped event writes
`epure_app` via `EPURE_APP_DATABASE_URL`	Dashboard `/api/v1/*` with RLS

Compose injects all three for the app container. Missing migrate URL exits on start. Missing ingest URL yields storage errors on write. Missing app URL 500s the dashboard.

Dashboard request shape:

Valid session cookie.
Confirm the user is a member of the org.
SET LOCAL app.current_org_id = '<uuid>' on that transaction.
Run queries as epure_app. Never trust a client-supplied org id for the session setting.

Ingest request shape:

Authenticate with the project DSN.
Resolve project_id.
Write as epure_ingest. Do not set app.current_org_id from the client.

Illustrative policy shape (paraphrased from the docs pattern; pin your own names to migrations):

-- illustrative: dashboard role reads events only for the session org
CREATE POLICY events_org_isolation ON events
  FOR SELECT
  TO epure_app
  USING (org_id = NULLIF(current_setting('app.current_org_id', true), '')::uuid);

-- FORCE ROW LEVEL SECURITY so table owners cannot bypass by accident
ALTER TABLE events FORCE ROW LEVEL SECURITY;

Events land in monthly partitions events_YYYY_MM. Project retention TTL is 14 / 30 / 90 days; old partitions drop. Issue aggregates remain after event TTL. That retention story is separate from RLS, but it is part of the same cheap-ops bet.

You do not need our binary to try the pattern. Any multi-tenant read API on Postgres can use a restricted role, SET LOCAL for the tenant key, and FORCE ROW LEVEL SECURITY.

Honest limits and failure checklist

Exception-only. RLS is defense-in-depth for dashboard reads. Not a full security whitepaper. Never "100% Sentry compatible."

Limits we accept:

No APM, session replay, profiling, logs product, or mobile suite.
Partial Sentry wire for error tracking. Official SDKs via DSN swap (migrate post). Not a clone of every SaaS feature.
Ingest is not protected by the same org RLS session as the dashboard. DSN leakage is a project-level problem.
RLS does not replace authn, authz, TLS, or password hygiene.
Idle stack ~82 MiB was measured 2026-09-12 on our box. Treat that as one data point, not a promise.

Failure checklist:

Dashboard connected with DATABASE_URL / epure. Migrations role can see everything. Use EPURE_APP_DATABASE_URL for /api/v1.
Forgot SET LOCAL app.current_org_id. Queries as epure_app return empty or error depending on policy. Fix the session setter, do not weaken the policy.
Trusting org id from the JSON body. Membership must drive SET LOCAL. Client UUID is not a credential.
DSN pasted into a dashboard /api/v1 call. Wrong path. Ingest uses the envelope/store routes and the ingest role.
Example passwords on a public EPURE_PUBLIC_URL. Boot refuses documented laptop defaults and leftover CHANGE_ME off localhost. Use the production env template.
Expecting RLS to hide events after a leaked project DSN. Rotate the key. RLS does not rewrite ingest auth.
Assuming event TTL deletes issue rows. Partitions drop; issue aggregates remain. Read retention docs before promising "everything gone."

Configuration map for the three URLs and roles: self-hosting configuration.

Discussion

Where do you put the tenant boundary for multi-tenant reads: app filters only, Postgres RLS, or separate databases per customer?

Migrate Sentry -> Epure in 10 min

Amorizz — Thu, 01 Oct 2026 13:27:10 +0000

TL;DR

Keep the official Sentry SDK. Change only dsn to your Epure project.
Set traces, profiles, and replay sample rates to 0. Epure is exception-only.
Throw one test error, expect ingest HTTP 202, then an Issues row. Know what you drop.

I already ship @sentry/node (and browser) against SaaS Sentry. This week I pointed the same init at our self-hosted ingest: same SDK, new DSN, one verified event. The bill and the data residency story were enough; I did not want a client rewrite.

About ten minutes of wall clock once the ingest host is healthy. That is DSN copy, init edit, one throw, Issues check. Not a stopwatch claim for compose, TLS, or CORS.

What do you need before the clock starts?

Ingest already up. Official Sentry SDK already in the app.

Prerequisite	Done means
Epure host	`/health` returns `{"status":"ok"}` on the public origin you will put in the DSN
Project + DSN	Dashboard → Settings → SDK connection (or Setup). Key created.
App SDK	You already call `Sentry.init` with a SaaS DSN
Scope match	You only need exceptions / issues, not APM, replay, profiling, logs, or mobile

Host not up yet? Bring the two-container stack online first (Error monitoring on a $5 VPS), then come back. This post does not retell compose.

Timed steps: DSN swap and one event

Copy the project DSN, replace only dsn, zero unused rates, throw once, confirm Issues.

1. Copy the project DSN

Open the project → Settings → SDK connection (or Setup). Create a DSN key if none exists. Copy the full string. Do not paste a project UUID from the URL bar into the DSN.

Shape looks like:

https://YOUR_PUBLIC_KEY@errors.example.com/YOUR_PROJECT_ID

2. Swap `dsn` only

CI fixtures pin @sentry/browser / @sentry/node 7.120.0. Match that if you want the same line the docs exercise. On Sentry JS v8+, also set enableTracing: false when the option exists.

import * as Sentry from "@sentry/node"; // or @sentry/browser@7.120.0

Sentry.init({
  dsn: "https://YOUR_PUBLIC_KEY@errors.example.com/YOUR_PROJECT_ID",
  environment: "production", // match the Issues filter chip
  release: "my-app@1.2.3",
  tracesSampleRate: 0,
  profilesSampleRate: 0,
  replaysSessionSampleRate: 0,
  replaysOnErrorSampleRate: 0,
});

Migrating from Sentry SaaS: keep the same init options. Replace only dsn.

3. Send one test error

Sentry.captureException(new Error("Epure migrate test"));
// short workers: await Sentry.flush(2000) before process exit

4. Confirm ingest, then Issues

Expect ingest HTTP 202 with a body like { "id": "..." }. Refresh Issues. Match the environment filter to Sentry.init (production above, or local in docs examples). You should see an unresolved issue for that message.

Empty feed after a 202? Wait a second, check the env chip, confirm you opened the project that owns the DSN.

What do you keep / drop?

Exceptions and issue triage stay. Replay, APM, profiling, logs, and mobile do not.

Keep	Drop (out of scope)
Official Sentry SDKs (`@sentry/node`, `@sentry/browser`, …)	Session replay
Envelope / store error path	APM / distributed tracing product
`environment`, `release`, issue grouping	Continuous profiling
Self-hosted data path	Full SaaS suite extras

Never "100% Sentry compatible." Partial wire for error tracking. If GlitchTip is a better fit for a lighter Django-shaped stack, that is fine. This post is that migrate path.

Deeper SDK init, CORS, and compose details live in the earlier how-to: Point the official Sentry SDK at self-hosted ingest (DSN only). Soft-link only. Do not retell every init step here.

Failure checklist

CORS blocks the browser SDK. SPA origin missing from EPURE_CORS_ORIGINS. Fix origins before blaming the package (CORS post).
Short worker exits before flush. Node/Go lambda-style processes drop the last event. Call flush / Flush before exit (flush post).
DSN revoked or wrong key. Secret shown once at create. Rotate in Settings → SDK connection if you pasted a dead key.
Public URL mismatch. /health on localhost is not the host inside the DSN. Align EPURE_PUBLIC_URL / proxy with what the SDK posts to.
Environment chip hides the row. Issues filter is staging while init says production. Match them.
Second Sentry.init still on SaaS. A leftover init in a shared bootstrap still ships to ingest.sentry.io. Grep for every Sentry.init and every dsn:.

When the host is healthy and you want the install map in one place: Epure quickstart.

Discussion

What blocked your last DSN swap: CORS, auth, or a missing flush on short workers?

Error monitoring on a $5 VPS

Amorizz — Mon, 28 Sep 2026 20:46:13 +0000

TL;DR

We run exception-only ingest on a $5-12 class VPS: two containers (app + Postgres 16), official Sentry SDKs via DSN swap.
We ruled out full self-hosted Sentry (dozens of containers) and a SaaS bill for errors-only work.
Postgres stays off the host port. TLS edge is a separate recipe (Caddy post); this post is cost + footprint + constraints.

I run Epure exception ingest on the same class of box I use for side projects: one cheap VPS, one engineer, no Kubernetes. The job is narrow. Catch production exceptions, group them, keep Postgres off the public internet. Not APM. Not session replay. Not a 65-container Sentry clone on a droplet that costs less than lunch.

Here are the notes from that choice: constraints, what we ruled out, a minimal compose sketch, and the failure checklist we hit while wiring it.

What constraints did we accept?

$5-12/month VPS, one operator, official Sentry SDKs pointed at our own DSN. Errors only.

Concrete box:

Constraint	What we mean
Budget	$5-12 class VPS (1-2 vCPU, modest RAM). Not a managed cluster.
Headcount	One engineer who can SSH, edit compose, read logs.
Client path	Official Sentry SDKs (`@sentry/node`, `sentry-go`, etc.). DSN swap. No custom client.
Scope	Exceptions / issues. No APM, replay, profiling, logs, or mobile suite.

If you need the full Sentry product surface, this post is the wrong shape. Keep SaaS or self-host the big stack on hardware sized for it.

What did we rule out?

Full self-hosted Sentry (~65 containers) and paying SaaS just for exception ingest.

Option	Why it lost for this job
Self-hosted Sentry	Real product. Also a real fleet (Kafka, ClickHouse, Redis, workers, …). Fine on a dedicated host. Painful on a $5 box when you only need errors.
SaaS Sentry (exceptions-only)	Works. You pay for a bill and a vendor boundary you may not want for a side project or a privacy-sensitive ingest path.
GlitchTip	Fair lighter alternative. Open source, Sentry-protocol-ish, smaller than full Sentry. We still chose Epure because we are building it and want Rust + Postgres RLS for our threat model. A GlitchTip reader can still use the VPS constraints below.

We are not saying "kill Sentry." We are saying: if the job is exceptions on a cheap VPS, the 65-container install is the wrong unit of deployment.

Epure is exception-only. Official SDKs + DSN. Not "100% Sentry compatible." If your checklist includes replay, APM, or profiling, stop here and pick a suite that actually ships those.

Mental model before compose

Internet → TLS edge (Caddy :443) → app:8080 (Docker net)
                                  → postgres:5432 (Docker net only, NO host publish)

Two containers for the product. Proxy in front for HTTPS. Database never bound to 0.0.0.0:5432 on the host.

For the TLS edge recipe (Caddyfile, 80/443, Postgres unpublished), use the live post: Put self-hosted exception tracking behind Caddy. This article does not rehash every Caddy stanza.

Minimal two-container compose

App + postgres:16. Publish the app (or leave it for Caddy on the Docker network). Do not publish Postgres to the host.

Sketch shaped like production (passwords via .env, no example defaults on a public URL):

# docker-compose.errors.yml (sketch; pin your own image tags)
services:
  app:
    image: ghcr.io/epure-sh/epure:latest   # pin a release tag in prod
    restart: unless-stopped
    env_file: [.env]
    environment:
      DATABASE_URL: postgres://epure:${POSTGRES_PASSWORD}@postgres:5432/epure
      EPURE_PUBLIC_URL: https://errors.example.com
      EPURE_CORS_ORIGINS: https://app.example.com
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "8080:8080"   # or omit and let Caddy reach app:8080 on the Docker net
    networks: [web]

  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: epure
      POSTGRES_USER: epure
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U epure -d epure"]
      interval: 5s
      timeout: 5s
      retries: 10
    # NO ports: stay on the Docker network only
    networks: [web]

volumes:
  postgres_data:

networks:
  web:

Bring it up:

docker compose -f docker-compose.errors.yml up -d
curl -sS http://127.0.0.1:8080/health

Expected:

{"status":"ok"}

Then put Caddy (or nginx) on 80/443 in front of 127.0.0.1:8080, point DNS, register, copy a project DSN, and captureException from an official SDK.

Canonical install steps (prod overlay, ./configure --prod, PaaS templates): Epure self-hosting installation.

Expected footprint (honest)

Qualitative only until we publish measured numbers.

Stack	Container count (order of magnitude)	Fit on $5-12 VPS?
Full self-hosted Sentry	Dozens (~65-class fleet with deps)	Usually no, not for errors-only
GlitchTip	Small multi-service compose	Often yes (lighter than full Sentry)
Epure (what we run)	2 (app + Postgres 16)	Designed for this class of box

We will not invent RAM figures. If you measure, paste docker stats and free -h in the comments. We will update this section with real numbers when we have them on a named plan.

Failure checklist

Postgres published to the host (5432:5432 "just for debugging"). Scanners find it. Drop the ports: block; reach DB only as postgres:5432 on the Compose network.
Laptop compose used as prod. Example passwords + localhost URL rules do not belong on a public hostname. Use the production overlay / env template from the docs.
No TLS, cookies broken. Secure session cookies need HTTPS. Finish the Caddy edge before you debug "login flaps."
Health is green, DSN host is wrong. /health on localhost is not the same as the public origin in the DSN. Match EPURE_PUBLIC_URL / proxy host to what the SDK posts to.
CORS blocks browser SDKs. SPA origin missing from allowlist. Fix origins before blaming the SDK (see our CORS post if you already hit this).
OOM while "just trying self-hosted Sentry." The fleet, not your app. Errors-only on two containers is the cheap-VPS shape; full Sentry wants a bigger host.
Expecting APM / replay / profiling. Exception-only stacks will not grow those features because you wished hard. Pick the product that matches the checklist.

If the two-container shape matches what you need, follow the install doc once, put TLS in front, swap the DSN on an official SDK, and confirm a test exception lands: self-hosting installation.

Discussion

What do you run on a cheap VPS for errors, and what blew the RAM first?

Your last error never arrives — flush before exit in Node (and Go)

Amorizz — Sun, 27 Sep 2026 13:22:15 +0000

TL;DR

captureException (and friends) queue the event. The HTTP POST is async.
process.exit / os.Exit / Lambda freeze can kill the process before that POST finishes. Dashboard stays empty.
Fix: await Sentry.flush() or await Sentry.close() in Node; sentry.Flush(2 * time.Second) in Go, before you die.

You ship a cron, a Lambda, a CLI, or a one-shot k8s Job. Something throws. You call captureException. The process exits. You refresh the error dashboard. Nothing. You re-check the DSN, blame "Sentry being flaky," then burn an afternoon on network paths that were fine the whole time.

The SDK did what you asked: it queued the event. The process died before the transport finished. This post is the portable flush recipe for Node (@sentry/node) and Go (getsentry/sentry-go). Same calls work against SaaS Sentry, GlitchTip, or any self-hosted ingest that speaks the Sentry protocol.

Why the last error vanishes

Capture is async. Exit ends the process. Anything still in the SDK queue never leaves the box.

Official SDKs do not block your handler on every captureException. They serialize the event, hand it to an internal transport, and return. That is correct for long-running servers: you do not want every error to stall a request.

Short-lived workers have a different lifetime. The job finishes in hundreds of milliseconds. You call process.exit(1) or the runtime freezes the Lambda. The event buffer still has work. No more event loop ticks. No more goroutine. The POST never happens.

Mental model: capture = "please send this soon." Flush/close = "block until the queue is empty (or the timeout hits), then I am allowed to exit."

Broken Node repro

Reproduce with captureException plus an immediate process.exit and no flush. Expect an empty issue stream even when the DSN is valid.

Pin the SDK you will actually run:

npm i @sentry/node@11

broken-worker.mjs:

import * as Sentry from "@sentry/node";

Sentry.init({
  dsn: process.env.SENTRY_DSN, // any valid Sentry-protocol DSN
  tracesSampleRate: 0,
});

async function main() {
  try {
    throw new Error("flush-demo: cron blew up");
  } catch (err) {
    Sentry.captureException(err);
    // looks done… it is not
    process.exit(1);
  }
}

main();

Run it:

SENTRY_DSN='https://PUBLIC@HOST/PROJECT' node broken-worker.mjs

Expected when broken

Process exits in a few ms with code 1.
Your ingest host / SaaS project shows no new issue for flush-demo: cron blew up (or it appears much later / never, depending on race).
You will be tempted to rotate the DSN. Do not. Watch the network next.

Optional sanity check: temporarily set debug: true in Sentry.init. You often see the SDK still preparing or sending when the process already died.

Fixed Node (flush / close)

Await Sentry.flush(timeoutMs) if the process might keep running, or Sentry.close(timeoutMs) right before exit. Both return a Promise<boolean>: true if the queue drained in time.

fixed-worker.mjs:

import * as Sentry from "@sentry/node";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 0,
});

async function main() {
  try {
    throw new Error("flush-demo: cron blew up");
  } catch (err) {
    Sentry.captureException(err);
    // drain the queue, then disable the client (safe before exit)
    const ok = await Sentry.close(2000);
    if (!ok) {
      console.warn("Sentry.close timed out; some events may be lost");
    }
    process.exit(1);
  }
}

main();

If you only need to drain and the process continues (batch of jobs in one process), prefer flush:

const ok = await Sentry.flush(2000);
// client stays enabled

SIGTERM / graceful shutdown (Compose, k8s, systemd):

async function shutdown(signal) {
  console.log(`got ${signal}, flushing Sentry`);
  await Sentry.close(2000);
  process.exit(0);
}

process.on("SIGTERM", () => {
  shutdown("SIGTERM");
});
process.on("SIGINT", () => {
  shutdown("SIGINT");
});

Pinned versions used in this post

Package	Pin
`@sentry/node`	`11` (tested shape against `11.0.0` docs APIs)

Expected when fixed

close / flush takes up to your timeout (here 2s) and resolves true on a healthy network path.
The issue for flush-demo: cron blew up shows up on the project within a few seconds.
lastEventId() (optional) returns an id after capture; after a successful flush you can correlate it in the UI.

AWS Lambda note: the runtime can freeze after your handler returns. Prefer flushing inside the handler before you return, not only on a process-level signal you may never see.

Go: Flush before os.Exit

Call sentry.Flush(timeout) before the program terminates. defer is fine for normal returns; os.Exit skips defers, so flush manually before Exit.

go get github.com/getsentry/sentry-go@v0.49.0

package main

import (
    "fmt"
    "os"
    "time"

    "github.com/getsentry/sentry-go"
)

func main() {
    err := sentry.Init(sentry.ClientOptions{
        Dsn: os.Getenv("SENTRY_DSN"),
    })
    if err != nil {
        fmt.Fprintf(os.Stderr, "sentry.Init: %v\n", err)
        os.Exit(1)
    }
    // covers normal return paths
    defer sentry.Flush(2 * time.Second)

    sentry.CaptureException(fmt.Errorf("flush-demo: job failed"))

    // os.Exit skips defers; flush first
    if !sentry.Flush(2 * time.Second) {
        fmt.Fprintln(os.Stderr, "sentry.Flush timed out; some events may be lost")
    }
    os.Exit(1)
}

Expected when fixed: Flush returns true and the exception appears on the project. When broken (capture + os.Exit with no Flush), you get the same empty-dashboard trap as Node.

Do not call Flush after every CaptureException in a hot loop. That turns async transport into sync spam. Flush at boundaries: end of job, before Exit, on shutdown.

Where this bites (and where it usually does not)

You need an explicit flush on short-lived processes. Long-running servers mostly get away without it, but SIGTERM handlers still benefit.

Runtime	Usually needs flush?	Why
Cron / systemd oneshot	Yes	Process exits as soon as the script ends
AWS Lambda / Cloud Functions	Yes	Freeze after return; buffer dies with the freeze
CLI / `go run` job	Yes	User hits Ctrl-C or you `os.Exit`
k8s Job / Compose `restart: "no"` one-shot	Yes	Same as cron
Long-running HTTP API	Usually no	Event loop / goroutines keep running; still flush on SIGTERM

If your "server" is actually a request-scoped worker that exits per message (some queue consumers), treat it like a cron.

Confirm steps + failure checklist

Confirm by forcing one known error, awaiting flush/close, and seeing that exact message in the project before you touch the DSN again.

Confirm

Use a disposable message string (flush-demo: …) so you can find it fast.
Run the fixed Node or Go snippet against a known-good DSN.
Assert flush/close/Flush returned true (log it).
Open the project: the issue exists with that message.
Re-run the broken variant once so you trust the difference is flush, not luck.

Failure checklist

process.exit / os.Exit before flush. Classic. Move exit after await close / Flush.
Forgot that os.Exit skips defer. Go: flush explicitly before Exit; do not rely on deferred Flush alone.
Timeout too short on a slow link. 2000 ms is a starting point; bump for cold starts / far regions, or accept loss and log false.
Lambda returns before flush. Await flush inside the handler; do not only register process signals.
Wrong DSN still possible. Flush succeeding with true but no UI event means auth/host/project mismatch. Fix DSN after flush is proven locally (debug transport logs help).
Sample rates / beforeSend dropping the event. Flush only drains what the SDK kept. A filter that returns null will never arrive.
Multiple clients / hubs. Flush the client that captured the event (or shut down each one you created).
Fire-and-forget close() without await. In Node, a floating promise loses the race to process.exit again.

Same flush rule on any self-hosted error host

The SDK calls above are host-agnostic: they drain the client queue toward whatever DSN you configured. Same pattern for SaaS Sentry, GlitchTip, or another Sentry-protocol ingest. If you need a place to stand that host up, the quickstart covers the basics.

Discussion

Did you lose a prod-only exception because the worker exited before flush, and how long did you chase the wrong DSN?

Fix CORS before you blame the SDK

Amorizz — Thu, 24 Sep 2026 13:49:54 +0000

TL;DR

The bug is usually the preflight (OPTIONS), not your fetch call or the client library.
Access-Control-Allow-Origin: * and credentials: 'include' never work together.
Echo an exact origin from an allowlist, not a wildcard, when the SPA and API sit on different hosts.

Your SPA lives on https://app.example.com. Your API lives on https://api.example.com. You open DevTools, hit a button, and get a red CORS error. The first instinct is to blame axios, the SDK, or “browser fetch being weird.”

Pause. Cross-origin requests that are not simple GETs almost always send an OPTIONS preflight first. If that preflight fails, the real request never leaves the browser, and nothing you change in the client will fix a missing or wrong response header on the API.

This post is a portable SPA→API CORS recipe: minimal repro, Express and Caddy configs that engineers actually paste, the credentials gotcha, and a failure checklist. No product tour. Just headers that make the browser happy.

Why “but curl works” lies

Curl never sends a CORS preflight. The browser does, and it can block the real request before your route handler runs.

From a terminal, curl -X POST https://api.example.com/v1/items -H 'Content-Type: application/json' -d '{}' talks HTTP like any other client. There is no same-origin policy. There is no Origin header the browser injects. There is no automatic OPTIONS probe.

In Chrome or Firefox, a cross-origin POST with Content-Type: application/json is a non-simple request. The browser first asks:

OPTIONS /v1/items HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type

If the API does not answer with the right Access-Control-* headers (or does not handle OPTIONS at all), DevTools shows a CORS failure. Your Node route for POST /v1/items may be perfect. You never reached it.

Mental model: curl proves the route and auth work. The browser proves the CORS policy works. Fix both.

Minimal browser repro

Reproduce with one fetch from https://app.example.com to https://api.example.com, then watch Network for a failed OPTIONS (or a successful POST with missing CORS headers on the response).

Serve a tiny page from the SPA origin (static file, Vite, whatever. Origin must be https://app.example.com):

<!DOCTYPE html>
<html>
  <body>
    <button id="go">Call API</button>
    <pre id="out"></pre>
    <script>
      document.getElementById("go").onclick = async () => {
        const out = document.getElementById("out");
        try {
          const res = await fetch("https://api.example.com/v1/items", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ name: "cors-check" }),
            // credentials: "include", // turn on only when you need cookies
          });
          out.textContent = `status ${res.status}\n` + (await res.text());
        } catch (err) {
          out.textContent = String(err);
        }
      };
    </script>
  </body>
</html>

Expected when CORS is broken

Console: something like TypeError: Failed to fetch (Chrome) or a CORS policy message naming Access-Control-Allow-Origin.
Network: an OPTIONS to /v1/items with status (failed), 403, or 404, or a POST that returns 200 in Network but still throws in JS because response headers omit CORS allowances.
You do not see a normal JSON body in the page until both preflight and response headers are correct.

Expected when CORS is fixed

Network: OPTIONS → 204 (or 200) with Access-Control-Allow-Origin: https://app.example.com (exact match).
Then POST → your real status (200 / 201 / 401…); JS reads the body without a CORS TypeError.

Swap hostnames for your staging domains and keep the same shape.

What the API must send

For a browser SPA on another origin, the API must answer preflight and real responses with an allowlisted Access-Control-Allow-Origin, plus methods and headers the SPA actually uses, and Allow-Credentials only if cookies (or other credentialed mode) are in play.

Minimum response headers for the repro above (no cookies):

Header	Typical value
`Access-Control-Allow-Origin`	`https://app.example.com` (from allowlist, not `*`)
`Access-Control-Allow-Methods`	`GET, POST, PUT, PATCH, DELETE, OPTIONS`
`Access-Control-Allow-Headers`	`Content-Type, Authorization` (mirror what the SPA sends)
`Access-Control-Allow-Credentials`	`true` only if you use `credentials: 'include'`
`Access-Control-Max-Age`	optional; e.g. `600` to cache preflight

Echo the request Origin when it is in the allowlist. Do not invent a second origin string.

Express (allowlist + optional credentials)

// npm i cors@2
import express from "express";
import cors from "cors";

const app = express();
app.use(express.json());

const allowlist = new Set([
  "https://app.example.com",
  "http://localhost:5173", // local Vite; drop in prod if you prefer
]);

app.use(
  cors({
    origin(origin, cb) {
      // non-browser / same-origin tools may omit Origin
      if (!origin || allowlist.has(origin)) return cb(null, true);
      return cb(new Error(`Origin ${origin} not allowlisted`));
    },
    methods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
    allowedHeaders: ["Content-Type", "Authorization"],
    credentials: false, // set true only when cookies / credentialed fetch
    maxAge: 600,
  })
);

app.post("/v1/items", (req, res) => {
  res.status(201).json({ ok: true, item: req.body });
});

app.listen(3000);

Manual OPTIONS (if you prefer not to use cors):

app.use((req, res, next) => {
  const origin = req.headers.origin;
  if (origin && allowlist.has(origin)) {
    res.setHeader("Access-Control-Allow-Origin", origin);
    res.setHeader("Vary", "Origin");
    res.setHeader(
      "Access-Control-Allow-Methods",
      "GET,POST,PUT,PATCH,DELETE,OPTIONS"
    );
    res.setHeader(
      "Access-Control-Allow-Headers",
      "Content-Type, Authorization"
    );
    // res.setHeader("Access-Control-Allow-Credentials", "true"); // only if needed
  }
  if (req.method === "OPTIONS") return res.sendStatus(204);
  next();
});

Expected: with the SPA on an allowlisted origin, DevTools shows OPTIONS 204 and Access-Control-Allow-Origin equal to that origin. A non-allowlisted origin stays blocked. That is the point of the list.

Caddy (allowlist + OPTIONS)

Put CORS on the API site block (or in front of a reverse proxy). Match an exact allowlisted Origin, then echo that value. Do not reflect arbitrary Origins.

api.example.com {
    # Exact Origin allowlist (values on one line are OR'd)
    @allowed header Origin https://app.example.com
    # Local Vite: OR localhost onto the same matcher:
    # @allowed header Origin https://app.example.com http://localhost:5173

    @preflight method OPTIONS

    handle @preflight {
        header @allowed {
            Access-Control-Allow-Origin "{http.request.header.Origin}"
            Access-Control-Allow-Methods "GET, POST, PUT, PATCH, DELETE, OPTIONS"
            Access-Control-Allow-Headers "Content-Type, Authorization"
            Access-Control-Max-Age "600"
            Vary Origin
            # Access-Control-Allow-Credentials "true"  # only if cookies
        }
        respond 204
    }

    handle {
        header @allowed {
            Access-Control-Allow-Origin "{http.request.header.Origin}"
            Access-Control-Allow-Methods "GET, POST, PUT, PATCH, DELETE, OPTIONS"
            Access-Control-Allow-Headers "Content-Type, Authorization"
            Vary Origin
        }
        reverse_proxy 127.0.0.1:3000
    }
}

Warning: reflecting any Origin (no allowlist matcher) is insecure once credentials are on. Any site can trigger credentialed requests against your API. Keep the @allowed matcher tight.

Expected: curl -i -X OPTIONS https://api.example.com/v1/items -H 'Origin: https://app.example.com' -H 'Access-Control-Request-Method: POST' returns 204 with Access-Control-Allow-Origin: https://app.example.com. A non-allowlisted Origin gets no CORS allowance. The same allowlisted origin in the browser repro then succeeds.

Credentials gotcha

If the SPA sends cookies (or credentials: 'include'), the API must return Access-Control-Allow-Credentials: true and an exact Access-Control-Allow-Origin. Never *.

Common own-goal:

// SPA
fetch(url, { credentials: "include", method: "POST", ... });

// API (broken)
res.setHeader("Access-Control-Allow-Origin", "*");
res.setHeader("Access-Control-Allow-Credentials", "true");

Browsers reject that combination. Spec rule: credentialed responses cannot use *. You must echo the precise requesting origin (https://app.example.com), and that origin must be on your allowlist.

Also check:

Cookie SameSite / Secure / domain. CORS success does not fix a cookie the browser refuses to store or send.
Authorization header alone does not require credentials: 'include'. Prefer bearer tokens in headers when you can; turn credentials on only for cookie sessions.

Confirm steps + failure checklist

Confirm with DevTools Network: green OPTIONS, exact Allow-Origin, then a readable POST body, then walk the checklist if anything is still red.

Confirm

Hard-refresh the SPA; clear “Disable cache” oddities if you were testing aggressively.
Filter Network by OPTIONS: status 2xx/204, headers match allowlist origin.
Inspect the following POST/GET: same Allow-Origin on the response (preflight alone is not enough for reading the body).
Console has no CORS TypeError; your pre / UI shows the JSON (or a real app error like 401. That is progress).
Repeat from a second origin that is not allowlisted. It must still fail.

Failure checklist

Missing OPTIONS route. Proxy or framework returns 404/405 on preflight; add middleware or Caddy handle @preflight.
Allow-Origin: * with credentials. Browser blocks; switch to exact origin echo.
Wrong origin string. https://app.example.com vs https://www.app.example.com vs trailing slash; allowlist the exact Origin header value.
Proxy stripping headers. CDN / nginx / Caddy upstream drops Access-Control-*; set headers at the edge that the browser sees.
Allow-Headers incomplete. SPA sends Authorization or a custom header not listed; preflight fails even when Origin is fine.
Only preflight fixed. OPTIONS OK but actual POST response omits CORS headers; apply the same policy to all methods.
HTTP vs HTTPS mismatch. SPA on https://, API redirect or mixed content; fix TLS before debugging CORS.
Cached bad preflight. Old Max-Age remembered; try a private window or wait out cache while iterating.

Same OPTIONS wall on another host

Any browser SDK that POSTs from your SPA origin to a different host hits the same preflight rules. Allowlist the SPA origin and set credentials correctly on that host too. If you need a place to stand an ingest host up, the self-hosting install notes cover the basics.

Discussion

What was your dumbest CORS own-goal: * with credentials, missing OPTIONS route, or a proxy stripping headers?

Deploy a Docker app on a VPS with Caddy (keep Postgres off the internet)

Amorizz — Wed, 23 Sep 2026 16:01:11 +0000

TL;DR

Most side projects die the same way on a cheap VPS: the app is up, Postgres is on :5432, and HTTPS is “later.”
The boring fix is one Compose file: Caddy on 80/443, your app on the Docker network, database unpublished.
Copy the stack below, point DNS, prove https://your.domain/health (or /), then ship.

Why your first VPS deploy feels cursed

You can docker compose up on a laptop in five minutes. On a public IP the same file often means:

The database is reachable from the internet (you published 5432 “just for debugging”).
No real HTTPS — you tested on http://IP:3000 and called it done.
Secrets in the repo — .env.example values made it to production.

None of that is exotic. It is the default path for a Node/Go/Python API with Postgres. This guide is the minimum production shape that fixes those three without Kubernetes.

You will end with:

Internet → :443 Caddy (TLS) → app:8080 (Docker net)
                              → db:5432 (Docker net only)

Only Caddy listens on the public host. Everything else stays inside Compose.

What you need

A VPS (Ubuntu 22.04/24.04 is fine) with a public IPv4
A domain (or subdomain) whose A record points at that IP
Docker Engine + Compose plugin installed
Ports 80 and 443 open (and 22 for SSH). Do not open 5432.

If Docker is missing:

# official convenience script — or use your distro’s docker.io + compose plugin
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker "$USER"
# log out/in, then:
docker compose version

The stack (app + Postgres + Caddy)

Create a project folder:

mkdir -p ~/apps/myapp && cd ~/apps/myapp

`docker-compose.yml`

Replace the app image with yours. The important bits are the network, no DB publish, and Caddy as the only public ports.

services:
  caddy:
    image: caddy:2.8
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    depends_on:
      app:
        condition: service_healthy
    networks: [web]

  app:
    image: your-registry/your-app:1.2.3   # pin a tag — avoid :latest in prod
    restart: unless-stopped
    env_file: [.env]
    environment:
      DATABASE_URL: postgres://app:${POSTGRES_PASSWORD}@db:5432/app
      PUBLIC_URL: https://app.example.com
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:8080/health"]
      interval: 10s
      timeout: 3s
      retries: 6
    networks: [web]
    # no ports: — Caddy reaches it as http://app:8080 on the Docker network

  db:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 5s
      timeout: 3s
      retries: 10
    networks: [web]
    # CRITICAL: no ports: section — Postgres stays off the host

networks:
  web:

volumes:
  postgres_data:
  caddy_data:
  caddy_config:

`Caddyfile`

app.example.com {
  encode gzip
  reverse_proxy app:8080
}

Caddy talks to the service name app on the shared Compose network. Do not proxy to localhost here — inside the Caddy container, localhost is Caddy itself.

Persist /data (the caddy_data volume). Without it, every recreate re-issues certificates and can burn Let’s Encrypt rate limits.

`.env` (on the server only)

POSTGRES_PASSWORD=$(openssl rand -base64 32)
# put the same value in .env — chmod 600 .env — never commit it

printf 'POSTGRES_PASSWORD=%s\n' "$(openssl rand -base64 32)" > .env
chmod 600 .env

Point DNS for app.example.com at the VPS before you expect a trusted cert. While debugging certs, you can temporarily add:

{
  acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

…so a broken config does not eat your weekly production quota. Remove staging when it works.

Bring it up

docker compose up -d
docker compose ps
docker compose logs -f caddy

Expected: caddy, app, and db healthy. Prove the boundary:

# public path
curl -sS -o /dev/null -w "%{http_code}\n" https://app.example.com/health

# Postgres must NOT be on the host
ss -lntp | grep 5432 || echo "good: nothing on host :5432"
docker compose port db 5432 2>/dev/null || echo "good: db has no published port"

If /health is not your route, hit / or whatever your app exposes. The point is: TLS works on the public name, and 5432 is invisible from the host.

Firewall (keep it boring)

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

Do not ufw allow 5432. Note: Docker’s published ports can bypass UFW on some setups — another reason to never publish the DB in Compose at all.

Updates without drama

docker compose pull app
docker compose up -d app
docker image prune -f

Pin image tags. Back up postgres_data (and caddy_data if you care about certs surviving a wipe) before you treat the VPS as disposable.

# example volume backup idea — adapt to your backup tool
docker run --rm -v myapp_postgres_data:/data -v "$(pwd)":/backup alpine \
  tar czf /backup/postgres_data.tgz -C /data .

Confirm checklist

[ ] Only 80/443 (and SSH) intentional on the host
[ ] https://your.domain works; HTTP redirects to HTTPS
[ ] App reached via service name from Caddy, not a published app port
[ ] Postgres not published (docker compose ps / no host :5432)
[ ] .env is chmod 600, not in git
[ ] Named volumes for DB + Caddy data
[ ] Healthcheck so Caddy does not proxy a migrating app forever

Failure checklist (≥5)

Published 5432 “temporarily” — scanners do not care that it was temporary. Remove the publish.
reverse_proxy localhost:8080 inside Caddy-in-Docker — wrong localhost. Use app:8080 on the Compose network (or publish the app on 127.0.0.1 and run Caddy on the host).
DNS not pointed yet — ACME fails; check docker compose logs caddy.
Burned Let’s Encrypt quota — use staging CA while iterating.
:latest in prod — surprise breakage on pull day. Pin tags.
Reused a laptop volume on the server — passwords and schemas diverge; prefer a fresh volume for first prod boot.
App still published on 0.0.0.0:3000 — you bypassed Caddy and skipped TLS. Drop the publish or bind 127.0.0.1 only if Caddy is on the host.

Where this pattern shows up next

Same shape — HTTPS edge, app private, Postgres private — applies to dashboards, APIs, and self-hosted tools. One public example of that two-container-behind-proxy idea for exception ingest (official Sentry SDKs + DSN host change, not APM/replay): self-hosting installation.

Discussion

When you first put a side project on a VPS, what bit you first — open Postgres, missing TLS, or secrets in git?

Point the official Sentry SDK at self-hosted ingest (DSN only)

Amorizz — Sun, 20 Sep 2026 10:00:44 +0000

You don’t need a forked Sentry SDK. Keep @sentry/browser or @sentry/node, change only dsn, then prove /health → HTTP 202 → Issues. Two containers (app + Postgres 16); leave replay, traces, and profiles at sample rate 0 — those envelope items are out of scope.

What you will do

Clone and docker compose up
Confirm GET /health → {"status":"ok"}
Install a pinned official SDK (7.120.0)
Sentry.init with your DSN and zeroed unused sample rates
captureException and expect ingest 202, then an Issues row
Optional: raw store / envelope curls if the SDK path is noisy

Two containers, one health check

Clone the public tree and start compose from the repo root:

git clone https://github.com/epure-sh/epure.git
cd epure
docker compose up

Two services: the app image and postgres:16-alpine. No Redis. No separate worker fleet on this laptop path.

If port 8080 is taken:

cp .env.example .env
# set EPURE_PORT and EPURE_PUBLIC_URL together, then recreate the app container

Wait for health:

curl -sS http://localhost:8080/health

Expected body:

{"status":"ok"}

Open http://localhost:8080. Register in the UI, or for local smoke only (never production):

./scripts/seed-dev.sh

Copy the DSN (only thing that changes)

From the dashboard: Settings → SDK connection (or the setup checklist). Create a key if none exists. Shape:

http://{public_key}@localhost:8080/{project_id}

Migrating from Sentry SaaS? Keep the same init options. Replace only dsn.

Init once, throw once

Pin the fixtures the public docs exercise:

# browser SPA
npm install @sentry/browser@7.120.0

# or Node API / worker
npm install @sentry/node@7.120.0

Browser example:

import * as Sentry from "@sentry/browser";

Sentry.init({
  dsn: "http://YOUR_PUBLIC_KEY@localhost:8080/YOUR_PROJECT_ID",
  environment: "local",
  release: "my-app@0.0.0",
  tracesSampleRate: 0,
  profilesSampleRate: 0,
  replaysSessionSampleRate: 0,
  replaysOnErrorSampleRate: 0,
});

Sentry.captureException(new Error("Epure quickstart test"));

Node is the same shape with @sentry/node. Set unused sample rates to 0. Transactions, session replay, and profiles are discarded on an exception-only host — zeroing them stops the SDK from sending work you will never see in Issues.

Confirm 202, then Issues

Ingest accepts before the Issues row appears. A successful SDK or store/envelope POST returns HTTP 202 with a body like:

{ "id": "660e8400-e29b-41d4-a716-446655440001" }

Refresh http://localhost:8080. Match the environment filter chip to Sentry.init (local in the example). You want an unresolved issue for Error / Epure quickstart test.

Empty feed copy looks like 0 UNRESOLVED EXCEPTIONS. That alone is not proof of failure — see the checklist below.

Optional: curl without an SDK

Useful when you need to separate “SDK wiring” from “host ingest.” Seed IDs below match ./scripts/seed-dev.sh in the public docs. Change host if EPURE_PORT is not 8080.

Legacy store JSON:

curl -sS -D - -o /tmp/epure-ingest.json -X POST \
  "http://localhost:8080/api/550e8400-e29b-41d4-a716-446655440000/store/" \
  -H "X-Sentry-Auth: Sentry sentry_version=7, sentry_key=a1b2c3d4e5f6g7h8i9j0, sentry_secret=supersecretdevkey" \
  -H "Content-Type: application/json" \
  -d '{
  "platform": "javascript",
  "exception": {
    "values": [{ "type": "Error", "value": "Epure try-it" }]
  }
}'

Expect HTTP/1.1 202 Accepted and an id in the JSON body.

Envelope path (same auth, binary body from the repo):

curl -sS -D - -o /tmp/epure-envelope.json -X POST \
  "http://localhost:8080/api/550e8400-e29b-41d4-a716-446655440000/envelope/" \
  -H "X-Sentry-Auth: Sentry sentry_version=7, sentry_key=a1b2c3d4e5f6g7h8i9j0, sentry_secret=supersecretdevkey" \
  -H "Content-Type: application/x-sentry-envelope" \
  --data-binary @fixtures/sentry/browser/envelope.txt

Endpoints that matter:

Method	Path
`POST`	`/api/{project_id}/store/`
`POST`	`/api/{project_id}/envelope/`
`GET`	`/health`

When 202 is a lie

202 means auth + schema accepted. It is non-blocking. It does not mean “row visible in Issues yet.”

Checklist when the feed stays empty after a 202:

Wait, then refresh — accept is ahead of the worker. One immediate refresh is not final.
Environment chip — UI filter must match environment in Sentry.init (local in the examples).
Project / DSN mismatch — open the project that owns the key you put in dsn.
Wrong host or port — EPURE_PUBLIC_URL / EPURE_PORT drift after a .env change without recreating the app container.
SDK still talking to SaaS — leftover dsn, or a second Sentry.init later in boot.

If store curl returns 202 but the SDK path does not, debug the client. If both miss 202, debug the host (docker compose logs on the app service, health, DSN key).

What this host is not

Exception-only lane. Do not expect APM, session replay, profiling, log product, or mobile SDKs to “just work” because the DSN looks familiar. JS/TS source maps are a separate verify step (upload + prove demangled frames) — out of scope here.

Do not write “100% Sentry compatible” in a PR description or a README badge. Honest subset: official SDK, DSN swap, exceptions, envelope/store.

FAQ

Does Sentry JS 8.x work?

Often yes. CI fixtures are 7.120.0. On v8+, set enableTracing: false when the option exists, and keep traces / profiles / replay sample rates at 0. Pin 7.120.0 if you want the same line the docs exercise. Confirm with a real throw, not only a green install.

Can I use Python or curl only?

Yes. Envelope and store accept official Sentry SDKs and raw JSON. Store is the smallest wire path. Phase 1 demangle stays JS/TS only, so frames stay as sent for other runtimes.

Do I need Redis?

No. Two containers for this path: app + Postgres 16.

Laptop compose in production?

No. Use the production overlay and a real .env from .env.production.example. Seed script and example DB passwords are local smoke only.

Canonical docs

Quickstart (this flow): https://epure.sh/docs/get-started/quickstart
Install / Postgres 16 / prod overlay: https://epure.sh/docs/self-hosting/installation

If those URLs 404 someday, the commands above still stand: health JSON, store/envelope 202, DSN host swap, sample rates at 0.

Discussion

After ingest returns 202 but Issues stays empty — do you check the environment chip, project/DSN match, or worker lag first?

DEV Community: Amorizz

Sentry caught my Express error. The request still hung forever

TL;DR

The smallest app that reproduces it

Run 1: Express 4, no SDK

Run 2: Express 4, with Sentry

Run 3: Express 5

The fix if you are stuck on Express 4

What I would check in your app today

Where I run this

What this does not show

Your .env hit git. Here's how I keep secrets on a VPS

TL;DR

What are you actually protecting?

How does .env end up in git?

What goes on the VPS?

Compose: env_file vs ${PASSWORD} in the YAML

The ${} gotcha inside command: strings

Failure checklist

Where this shows up for me

Write a Docker Compose healthcheck that actually checks your app

TL;DR

What does a healthcheck actually prove?

Why did pg_isready say healthy too early?

The Compose file that tells the truth

The /healthz and /readyz handlers

Check it: start, then break the database

Should the Docker healthcheck call /healthz or /readyz?

Failure checklist

Where this runs for me

Your sampleRate won't save you from an error flood. Here's what does

TL;DR

Why doesn't sampleRate fix an error flood?

The flood lab: one loop, three rare bugs

Run 1: the SDK drops more than you think

Run 2: sampleRate 0.1 loses the rare bugs

Run 3: count everything, ration the bodies

How the spike valve works in Epure

Why not a project-level limit?

When is sampleRate still the right call?

Failure checklist

What would you set?

Why Rust + Postgres RLS

TL;DR

Why Rust + Postgres RLS for exception ingest?

Threat model: who can read what if X fails?

Why not a shared DB without RLS, app-only filters, or a heavier stack?

Working sketch: three roles, SET LOCAL, policy shape

Honest limits and failure checklist

Discussion

Migrate Sentry -> Epure in 10 min

TL;DR

What do you need before the clock starts?

Timed steps: DSN swap and one event

1. Copy the project DSN

2. Swap dsn only

3. Send one test error

4. Confirm ingest, then Issues

What do you keep / drop?

Failure checklist

Discussion

Error monitoring on a $5 VPS

TL;DR

What constraints did we accept?

What did we rule out?

Mental model before compose

Minimal two-container compose

Expected footprint (honest)

Failure checklist

Discussion

Your last error never arrives — flush before exit in Node (and Go)

TL;DR

Why the last error vanishes

Broken Node repro

Fixed Node (flush / close)

Go: Flush before os.Exit

Where this bites (and where it usually does not)

Confirm steps + failure checklist

Same flush rule on any self-hosted error host

Discussion

2. Swap `dsn` only

`docker-compose.yml`

`Caddyfile`

`.env` (on the server only)