After building the AWS Landing Zone and multiple infrastructure projects, I've developed opinions about how to write Terraform modules that other people can actually use.

The Module Structure

Every module follows this structure:

\

My CI pipeline used to take 45 minutes. It now takes 8. The biggest wins came from Docker optimization — not faster hardware.

The Problem

Every CI run was:

1. Pull base image (2 min)
2. Install OS dependencies (5 min)
3. Install Python packages (8 min)
4. Install Node packages (6 min)
5. Build application (4 min)
6. Run tests (15 min)
7. Build production image (5 min)

Total: ~45 minutes. Developers stopped running the full pipeline. Bugs slipped through.

Fix 1: Multi-Stage Builds (45 → 30 min)

\

The Nexural ecosystem has 185 database tables, 69 API endpoints, real-time market data, AI-powered features, and a live quality dashboard. My AWS bill is under $50/month.

Here's how.

The Architecture That Saves Money

Principle: use managed services at their free/cheap tiers instead of running your own infrastructure.

Total: ~$25-45/month for a production platform.

The Tricks

1. Supabase Instead of RDS

A Supabase Pro instance is $25/month and includes:

• PostgreSQL 15 with 8GB storage
• Row-level security
• Real-time subscriptions
• Built-in authentication
• Auto-backups

An equivalent RDS instance (db.t3.micro) is $15/month but you need to manage backups, auth, and real-time yourself. Add those services and you're at $60+.

2. Lambda for Spiky Workloads

The telemetry ingestion API handles 0 requests most of the time, then bursts during CI runs. Lambda is perfect: $0 when idle, pennies during bursts.

\

Static AWS keys in CI are a footgun.

If you want cloud automation that scales (and passes security review), use OIDC-based federation:

• GitHub Actions issues a short-lived identity token (OIDC)
• AWS STS exchanges it for short-lived AWS credentials
• Your workflow assumes a least-privilege role and does the work

This portfolio uses the same pattern to support Cloud telemetry mode (AWS S3) without ever embedding long-lived credentials.

The architecture

\

Every project plan I've ever written has a line item: "Authentication — 2 days."

Every project retrospective has a note: "Auth took 2 weeks."

I've built auth systems 4 times now. Each time, I underestimate it. Here's why, and what I finally learned.

The Iceberg

What you think auth is:

• Login form
• Store a token
• Check if token is valid
• Done

What auth actually is:

• Login form (email/password + OAuth + magic links + MFA?)
• Password hashing (bcrypt, argon2, what cost factor?)
• Session management (JWT vs session cookie vs both?)
• Token refresh (silent refresh, rotation, revocation)
• CSRF protection (same-site cookies, double-submit token)
• Rate limiting (on login, on registration, on password reset)
• Password reset flow (token generation, expiry, single-use)
• Email verification (token, resend logic, what if they change email?)
• Account lockout (how many attempts? What's the unlock flow?)
• Role-based access (admin vs user vs moderator)
• API key management (for programmatic access)
• Session invalidation on password change
• "Remember me" vs "this session only"
• Login from new device notification
• Audit logging (who logged in, when, from where)

That's 15+ features. At 1-2 days each, you're looking at a month.

What I Do Now: Use Supabase Auth and Extend

After building custom auth twice and hating my life both times, I now start with Supabase Auth (or Clerk, or Auth.js). It handles:

• Email/password with bcrypt
• OAuth providers (Google, GitHub, Discord)
• JWT tokens with refresh
• Email verification
• Password reset
• Session management
• Rate limiting

That's 80% of auth, handled by people who think about auth full-time. I focus on the 20% that's specific to my app:

\\

Nobody puts "implement rate limiting" on the sprint board. It's not a user story. It doesn't move a metric. Product never asks for it.

Then one day, someone scripts 50,000 requests to your API in 30 seconds and your database melts. Or worse — a single user's runaway script costs you $800 in AWS Lambda invocations overnight.

Both of these happened to me. Now rate limiting is in my starter template.

The Three Layers

I implement rate limiting at three layers, because each catches different abuse patterns:

Layer 1: Edge (CloudFront / Vercel)

\\

I've been running Supabase in production for over a year. 185 tables. 69 API endpoints. Stripe webhooks. Real-time subscriptions. Discord bot data. Trading analytics.

This isn't a "getting started" tutorial. This is the honest review after living with it at scale.

What's Genuinely Incredible

Row-Level Security Changes Everything

RLS is Supabase's killer feature, and most people underuse it. Instead of writing authorization checks in every API endpoint, the database enforces access:

\\

Quick audit: where is your database password right now?

If you answered ".env file in the repo root" — you're in the majority. If you answered "also in a Slack message to the new hire, a screenshot in Confluence, and hardcoded in that one Lambda function that Dave wrote before he left" — you're being honest.

Environment variables are the most dangerous infrastructure in most startups because everyone treats them as an afterthought.

The Common Mistakes

Mistake 1: .env in Version Control

I've seen it in production repos at real companies. A \\

I once inherited a Grafana instance with 47 dashboard panels. CPU utilization, memory usage, disk I/O, network bytes, JVM heap — every metric you could imagine. Everything was green. All the time.

Two days later, the API went down for 4 hours. Not a single alert fired.

Why? Because CPU was at 22%, memory at 45%, and disk at 30%. All "healthy." The actual problem was a connection pool exhaustion — a metric nobody was watching.

The Four Golden Signals (and Nothing Else)

Google's SRE book nailed this. You need exactly four signals:

1. Latency — How long do requests take? Not average latency — that hides problems. Track P50, P95, and P99:

• P50 = 200ms means half your users get responses in 200ms (good)
• P95 = 800ms means 1 in 20 users waits 800ms (acceptable)
• P99 = 5000ms means 1 in 100 users waits 5 seconds (problem)

Your P99 is your real performance. The average lies.

2. Traffic — How many requests are you handling? This is your baseline. If traffic drops 80% at 2pm on a Tuesday, something is wrong even if all other metrics are green.

3. Errors — What percentage of requests fail? Track error rate, not error count. 100 errors out of 1 million requests (0.01%) is fine. 100 errors out of 200 requests (50%) is an outage.

4. Saturation — How full is your system? Database connections, memory, queue depth, thread pools. When any resource hits 80% utilization, you need to act — not because it's broken, but because you've lost your headroom.

My Actual Monitoring Setup

For the Nexural platform:

\\

Picture this: your Docker Compose setup works perfectly on your local machine. You push to CI, and suddenly every integration test fails with Connection refused.

The database container is "running." The API container is "healthy." The test process starts. Then it cannot connect to the service it needs.

This failure looks random until you remember one thing: local Docker networking and CI Docker networking are not the same environment.

:::proof-note title="The actual lesson" label="ci note" Most Docker Compose connection errors in CI are not Docker problems. They are timing, hostname, port, or network-boundary problems that local development hides. :::

The local setup lies to you

On your machine, you might connect to Postgres at localhost:5432.

Inside a Compose network, another container should usually connect to postgres:5432, where postgres is the service name.

In CI, the test runner may be:

• inside the Compose network
• outside the Compose network on the host
• inside a CI service container
• inside a nested Docker executor

Those four cases use different hostnames.

That is why a connection string can be "correct" locally and wrong in the pipeline.

First, identify where the test process runs

Before changing ports, ask one question:

Is the test command running inside a Compose service or on the CI host?

If tests run inside Compose:

DATABASE_URL=postgres://user:pass@postgres:5432/app

If tests run on the CI host and Compose published the port:

DATABASE_URL=postgres://user:pass@127.0.0.1:5432/app

If tests run in a separate CI container, neither may work until the CI platform's service networking is configured.

:::system-diagram title="CI networking decision" label="compose -> tests" nodes="Compose service,Network,Test runner,Database" The right hostname depends on where the test runner lives. Service names work inside the Compose network. Published localhost ports work from the host. :::

Do not trust depends_on as readiness

depends_on can control start order. It does not guarantee that Postgres, Redis, or your app is ready to accept connections.

The common bad version:

services:
  api:
    depends_on:
      - postgres

That only means the postgres container starts before api. It does not mean migrations ran. It does not mean TCP is ready. It does not mean the database accepted authentication.

Use health checks or an explicit wait script.

services:
  postgres:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      timeout: 5s
      retries: 12

  api:
    depends_on:
      postgres:
        condition: service_healthy

That still does not solve every CI platform, but it removes the most common race.

Check the four failure classes

When I see Connection refused, I work through this order.

:::checklist title="Docker Compose CI checklist" label="debug order"

• Confirm the test runner location: host, Compose service, or CI service container
• Confirm the hostname: service name vs 127.0.0.1 vs platform service alias
• Confirm the published port is actually mapped
• Confirm the dependency is healthy before tests start
• Print the resolved environment variables in CI without leaking secrets
• Run a tiny TCP check before the full test suite :::

The TCP check is boring but useful:

node -e "require('net').connect(5432, process.env.DB_HOST).on('connect', () => { console.log('ok'); process.exit(0) }).on('error', e => { console.error(e.message); process.exit(1) })"

If that fails, your application test suite is not the thing to debug yet.

Use different connection strings for different boundaries

One clean pattern is to make the boundary explicit:

DATABASE_URL_INTERNAL=postgres://app:app@postgres:5432/app
DATABASE_URL_HOST=postgres://app:app@127.0.0.1:5432/app

Then your CI job chooses the right one based on where the command runs.

This is less magical than trying to make one URL work everywhere.

:::scorecard title="Connection-string sanity check" label="scorecard" Runner location | Hostname | Port source Inside Compose | postgres | Container port CI host | 127.0.0.1 | Published port CI service container | Service alias | Platform service config Remote DB | Public/private DB host | Network allowlist :::

Keep migrations separate from readiness

A database can be healthy before the schema is ready.

If your app needs migrations, make that an explicit pipeline step:

docker compose up -d postgres
docker compose run --rm migrate
docker compose run --rm test

Or run tests inside a service that waits for both:

• database health
• migrations complete
• seed data loaded

Otherwise you get a worse class of failure: intermittent test errors that look like app bugs but are really setup races.

The debug output I want in every CI failure

Do not dump secrets. Do print the shape of the environment.

Useful output:

• Docker Compose services and status
• container logs for the dependency
• resolved host and port, with password redacted
• network names
• health-check status
• migration status

Example:

docker compose ps
docker compose logs --tail=80 postgres
docker network ls

The goal is to make the next failure diagnosable in one pass.

The production lesson

CI networking pain is a preview of production integration pain.

If your tests depend on hope, your deployments probably do too. Make service boundaries explicit. Add health checks. Split readiness from migrations. Log the right facts.

That is how you turn "works on my machine" into something a pipeline can prove.

:::offer-cta title="Need the pipeline cleaned up?" label="next step" href="/tools/route-finder" cta="Find your route" Use the diagnostic to decide whether this is a focused audit sprint, a platform build, or an academy path you can work through yourself. :::