You have a powerful computer sitting under your desk. Meanwhile, you're paying $50–200/month to run your MVP on someone else's computer. Let's fix that.

This guide walks through how I set up a home server with Cloudflare Tunnel to host multiple web apps — for $0/month in infrastructure costs. I'll also share a real debugging war story about HTTPS that'll save you hours.

The Problem

Cloud server costs add up fast when you're building:

Run two or three apps and you're easily at $100–200/month before you have a single paying customer.

Meanwhile, your home machine — probably 16–64 GB RAM, 8+ cores, 1 TB SSD — is idle 80% of the time.

The catch has always been: how do you expose a home machine to the internet without a static IP, port forwarding, and a prayer?

Cloudflare Tunnel.

The Architecture

Here's how traffic flows:

Browser (HTTPS)
    ↓
Cloudflare Edge (terminates TLS)
    ↓ (encrypted tunnel, outbound from your machine)
cloudflared daemon (your home machine)
    ↓ (HTTP)
Traefik reverse proxy (port 80)
    ↓ (HTTP)
Your app containers (Ghost, Postgres, whatever)

The key insight: your machine makes an outbound connection to Cloudflare. No port forwarding. No static IP. No firewall holes. Cloudflare routes incoming requests back through that persistent connection.

What You Need

• A home machine — Linux recommended (Ubuntu/Debian). Any old desktop or mini PC works.
• Cloudflare account — Free tier is enough.
• A domain — Pointed to Cloudflare's nameservers.
• Docker — For running your apps.
• Coolify — Self-hosted PaaS (free Heroku alternative). Or use Docker Compose directly.

Step 1: Install cloudflared

Install the Cloudflare Tunnel daemon:

# Debian/Ubuntu
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb -o cloudflared.deb
sudo dpkg -i cloudflared.deb

# Authenticate with your Cloudflare account
cloudflared tunnel login

# Create a tunnel
cloudflared tunnel create office

This gives you a tunnel ID and a credentials JSON file. Note both — you'll need them.

Install it as a system service so it survives reboots:

sudo cloudflared service install
sudo systemctl enable cloudflared
sudo systemctl start cloudflared

Step 2: Configure the Tunnel

Here's my real config.yml (at ~/.cloudflared/config.yml):

tunnel: a564a227-4d0d-4d12-92fe-e88298de08e8
credentials-file: /home/kevin/.cloudflared/a564a227-4d0d-4d12-92fe-e88298de08e8.json

ingress:
  # Coolify dashboard
  - hostname: coolify.httprapidoccasions.com
    service: http://localhost:8000

  # SSH access (must be before wildcard)
  - hostname: ssh.httprapidoccasions.com
    service: tcp://localhost:22

  # Wildcard — all deployed apps route through Coolify's Traefik
  - hostname: "*.httprapidoccasions.com"
    service: http://localhost:80

  # Catch-all
  - service: http_status:404

The magic is the wildcard rule. Any subdomain (app1.yourdomain.com, app2.yourdomain.com) routes to Traefik on port 80, which then routes to the right container. Deploy a new app, give it a subdomain — it just works.

DNS Setup

In your Cloudflare dashboard, add a wildcard CNAME:

Type: CNAME
Name: *
Target: <tunnel-id>.cfargotunnel.com
Proxy: enabled (orange cloud)

And one for the base domain or specific subdomains as needed.

Step 3: Set Up Coolify

Coolify is a self-hosted PaaS — think Heroku or Vercel, but free and running on your own machine. It gives you:

• Git push deployments
• Automatic SSL (via Traefik, which it manages)
• Database provisioning (Postgres, MySQL, Redis, etc.)
• A web dashboard for managing everything

Install with one command:

curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

After installation, access the dashboard at http://localhost:8000 (or through your tunnel at coolify.yourdomain.com).

Coolify runs Traefik as its reverse proxy on port 80. This is what the wildcard ingress rule in our tunnel config points to.

Step 4: Deploy Your First App

Let's deploy Ghost (the blogging platform) as an example.

In Coolify:

1. New Resource → Docker Compose
2. Paste your compose config or connect a Git repo
3. Set the domain to blog.yourdomain.com
4. Deploy

Coolify handles the Traefik labels, container networking, and routing. Your app is live at https://blog.yourdomain.com within minutes.

Want another app? Same process, different subdomain. The wildcard tunnel + wildcard DNS means zero infrastructure changes per app.

The HTTPS Gotcha (This Will Save You Hours)

Here's where I burned time so you don't have to.

The Symptom

After deploying Ghost behind Cloudflare Tunnel, things looked wrong:

• Infinite redirect loops (ERR_TOO_MANY_REDIRECTS)
• Mixed content warnings — the page loads but CSS/JS references http:// URLs
• Admin panel redirecting to HTTP and breaking

The Root Cause

The TLS/HTTP handoff creates a mismatch:

1. The browser connects to Cloudflare over HTTPS
2. Cloudflare terminates TLS and forwards to your tunnel over HTTP
3. Traefik receives the request as HTTP
4. Your app sees an HTTP request and thinks: "I'm not on HTTPS" — generates HTTP URLs, forces redirects, etc.

The app doesn't know the original request was HTTPS because nobody told it.

The Fix (Two Parts)

Part 1: Traefik middleware to set X-Forwarded-Proto

Add middleware to Traefik that tells your apps "the original request was HTTPS":

# In your Traefik dynamic config or Docker labels:
labels:
  - "traefik.http.middlewares.https-scheme.headers.customrequestheaders.X-Forwarded-Proto=https"
  - "traefik.http.routers.your-app.middlewares=https-scheme"

This injects the X-Forwarded-Proto: https header into every request reaching your app.

Part 2: Tell your app to trust the proxy

Most web frameworks ignore X-Forwarded-* headers by default (to prevent spoofing). You need to explicitly enable proxy trust.

For Ghost, set this environment variable:

environment:
  server__trustProxy: "true"

For other frameworks:

Part 3: Cloudflare SSL setting

In Cloudflare Dashboard → SSL/TLS, set the encryption mode to Full (not "Flexible"). Flexible tries to connect to your origin over HTTP and can cause redirect loops when your app expects HTTPS.

The Pattern

This three-part fix works for every app behind Cloudflare Tunnel + Traefik:

1. Traefik injects X-Forwarded-Proto: https
2. App trusts proxy headers
3. Cloudflare SSL mode set to Full

Internalize this pattern. You'll use it every time.

Cost Comparison

The home server costs you electricity and a domain. That's it. For MVP stage, that's the right answer.

When to Move to the Cloud

The home setup is great for MVPs and early traction, but you'll outgrow it when:

• You need uptime guarantees. Home internet goes down. Power goes out. Your setup has zero redundancy. If a customer SLA matters, move to the cloud.
• Latency matters. Your home server is in one location. Cloud providers have regions worldwide. If users in Asia are hitting a server in your apartment in Ohio, they'll notice.
• You're scaling past your hardware. When your apps need more RAM/CPU than your machine has, it's time.
• Security requirements increase. Enterprise customers will ask about SOC 2, data residency, etc. "It's in my office" is not the answer they want.
• Your team grows. Multiple engineers need access to infrastructure. Cloud platforms have better IAM, audit logs, and collaboration tools.

The good news: if you're using Docker and Coolify, migrating is straightforward. Export your compose files, spin up a VPS, deploy. The app doesn't care where it runs.

Conclusion

The best infrastructure for an MVP is the one that costs nothing and gets out of your way.

Cloudflare Tunnel + a home machine + Coolify gives you:

• Unlimited apps on a single machine with wildcard routing
• HTTPS everywhere with zero certificate management
• Git-push deploys through Coolify's dashboard
• $0/month infrastructure cost

Stop paying cloud providers to run your prototype. Ship from home, get users, validate the idea — then spend money on infrastructure when the revenue justifies it.

Copying This Article to Another Machine

Since the home server has SSH access through the tunnel, you can pull this file from any machine:

scp kevin@ssh.httprapidoccasions.com:/home/kevin/Development/personal/innovate-hub/infra/office-tunnel/blog-home-server-mvp.md ./blog-home-server-mvp.md

Or if using a non-standard SSH port or key:

scp -i ~/.ssh/your_key kevin@ssh.httprapidoccasions.com:/home/kevin/Development/personal/innovate-hub/infra/office-tunnel/blog-home-server-mvp.md .

Note: SSH through Cloudflare Tunnel requires the client to use cloudflared access as a proxy. Set up your ~/.ssh/config:

Host ssh.httprapidoccasions.com
    ProxyCommand cloudflared access ssh --hostname %h
    User kevin

Then scp works as normal:

scp ssh.httprapidoccasions.com:/home/kevin/Development/personal/innovate-hub/infra/office-tunnel/blog-home-server-mvp.md .

If you're a tmux power user, you know the pain. You've spent time crafting the perfect workspace—multiple windows for different projects, panes split just right, each one positioned in its correct directory. Then your computer restarts, or you close the terminal by accident, and it's all gone.

What if you could snapshot your entire tmux setup and restore it with a single command?

That's exactly what this toolkit does.

The Problem with Tmux Sessions

Tmux is incredible for managing terminal workflows. It lets you:

• Create multiple windows within a single terminal
• Split windows into panes
• Detach and reattach sessions
• Keep processes running in the background

But here's what tmux doesn't do well: persistent layouts.

Sure, you can detach a session and it keeps running. But what about:

• Saving a layout to use on a different machine?
• Keeping multiple layout configurations for different types of work?
• Recovering your setup after a reboot?
• Sharing your workspace configuration with teammates?

That's where these scripts come in.

The Toolkit: Three Simple Commands

This toolkit consists of three bash scripts that work together:

All layouts are stored in ~/.tmux-layouts/ as simple, human-readable files.

Installation

1. Clone or copy the three scripts to a directory in your PATH:

# Option 1: Copy to /usr/local/bin
sudo cp tmux-save tmux-load tmux-list /usr/local/bin/

# Option 2: Add the script directory to your PATH
echo 'export PATH="$PATH:/path/to/tmux-tools"' >> ~/.bashrc

1. Make them executable:

chmod +x tmux-save tmux-load tmux-list

That's it. No dependencies beyond bash and tmux itself.

How It Works

Saving a Layout: tmux-save

When you run tmux-save, it captures:

• Every window in your current session (name and layout)
• Every pane within each window (position, working directory, running command)
• The exact layout geometry so panes are restored to the same proportions

Usage:

# Save with a specific name
tmux-save myproject

# Or run without arguments to be prompted for a name
tmux-save
# Enter a name for this layout: myproject

Output:

✅ Layout 'myproject' saved to /Users/you/.tmux-layouts/myproject.layout

What gets saved (example layout file):

# tmux layout: myproject
# saved: Thu Feb 6 17:30:00 PST 2026
# session: dev

WINDOW|0|editor|a]f6,208x54,0,0{104x54,0,0,1,103x54,105,0,2}
PANE|0|0|/Users/you/projects/myapp|nvim
PANE|0|1|/Users/you/projects/myapp|zsh
WINDOW|1|servers|5b23,208x54,0,0,3
PANE|1|0|/Users/you/projects/myapp|npm
WINDOW|2|logs|5b24,208x54,0,0,4
PANE|2|0|/var/log|tail

The format is intentionally simple. You can even edit these files by hand if needed.

Loading a Layout: tmux-load

Restoring a layout is just as easy. tmux-load handles three scenarios automatically:

1. Running outside tmux — Creates and attaches to a new session
2. Running inside tmux — Creates the session and switches to it
3. Reloading the current session — Rebuilds in place without losing your terminal

Usage:

# Load by name directly
tmux-load myproject

# Or run without arguments to see a menu
tmux-load

Interactive menu output:

📋 Saved tmux layouts:

  1) myproject  (Thu Feb 6 17:30:00 PST 2026)
  2) backend-work  (Wed Feb 5 09:15:00 PST 2026)
  3) writing  (Mon Feb 3 14:22:00 PST 2026)

Select a layout (number) or 'q' to quit: 1

What happens when you load:

• A new tmux session is created with the name tmux-<layout-name>
• Each window from the saved layout is recreated with its original name
• Each pane is recreated, positioned, and cd'd to its saved directory
• The original window layouts (split proportions) are restored

Result:

✅ Layout 'myproject' restored as session 'tmux-myproject'

Managing Layouts: tmux-list

See all your saved layouts at a glance:

tmux-list

Output:

📋 Saved tmux layouts:

  📁 myproject
     Saved: Thu Feb 6 17:30:00 PST 2026 | Session: dev | Windows: 3 | Panes: 4

  📁 backend-work
     Saved: Wed Feb 5 09:15:00 PST 2026 | Session: api | Windows: 2 | Panes: 5

  📁 writing
     Saved: Mon Feb 3 14:22:00 PST 2026 | Session: docs | Windows: 1 | Panes: 2

Delete a layout:

tmux-list -d
# or
tmux-list --delete

This shows an interactive menu to select and delete a layout.

Real-World Use Cases

1. Project-Specific Workspaces

Save different layouts for different projects:

# Working on the frontend
tmux-save frontend-dev

# Switch to backend work
tmux-load backend-dev

2. Role-Based Setups

Create layouts for different types of work:

• tmux-save coding — Editor + terminal + test runner
• tmux-save debugging — Logs + debugger + shell
• tmux-save writing — Clean single-pane setup for documentation

3. Machine Migration

Moving to a new laptop? Copy your ~/.tmux-layouts/ directory and all your workspace configurations come with you.

4. Team Standardization

Share layout files with your team. Everyone gets the same development environment structure.

Tips and Tricks

Alias for Quick Access

Add these to your .bashrc or .zshrc:

alias ts='tmux-save'
alias tl='tmux-load'
alias tls='tmux-list'

Combine with tmux Hooks

You can auto-save your layout when detaching:

# In ~/.tmux.conf
set-hook -g client-detached 'run-shell "tmux-save autosave"'

Create a "Default" Layout

Save your ideal starting point:

tmux-save default

Then start every day fresh:

tmux-load default

How It Compares to Alternatives

This toolkit sits in a sweet spot: simpler than tmuxinator (no YAML to write), more flexible than tmux-resurrect (multiple named layouts), and zero dependencies.

Limitations

To keep things simple, these scripts don't capture:

• Running processes — The command is noted but not restarted
• Shell history — Each pane starts fresh
• Scroll buffer — Terminal output isn't preserved
• Environment variables — Pane-specific env vars aren't saved

If you need those features, look into tmux-resurrect with tmux-continuum. But for most workflows, saving the structure and directories is 90% of the value.

The Code

The entire toolkit is about 200 lines of bash. No magic, no complexity. The format is simple enough that you could write your own layout files by hand if you wanted to.

Layout file format:

# tmux layout: <name>
# saved: <date>
# session: <original-session-name>

WINDOW|<index>|<name>|<layout-string>
PANE|<window-index>|<pane-index>|<path>|<command>

Feel free to version control your layouts, share them, or build tooling on top.

Conclusion

Terminal workflows shouldn't be ephemeral. With tmux-save, tmux-load, and tmux-list, you can:

• Capture your perfect workspace in seconds
• Restore it anywhere, anytime
• Manage multiple configurations effortlessly

No plugins. No dependencies. Just three scripts and you're done.

Stop rebuilding your tmux setup. Start saving it.

Quick Reference

# Save current session
tmux-save <name>

# Load a saved layout (interactive)
tmux-load

# Load a specific layout
tmux-load <name>

# List all layouts
tmux-list

# Delete a layout
tmux-list -d

Layouts are stored in: ~/.tmux-layouts/

The Threshold

There's a red gate in Tokyo that changed how I see clothes.

Not a metaphorical gate. An actual one—a torii, vermillion and weathered, standing in a bamboo garden where I stood wrapped in fabric that took 400 years to perfect.

The Japanese call the color of these gates shu. The rest of us call it red. But shu isn't just a color. It's protection. It's vitality. It's the boundary between the world you came from and something else entirely.

I walked through one wearing a stranger's history on my shoulders.

What You're Actually Wearing

Here's what nobody tells you about putting on a kimono:

It takes 12 separate pieces.

There's the hadajuban (an undergarment to absorb sweat), the nagajuban (a longer under-robe), the kimono itself, the obi (that impossibly wide belt), obi-ita (a stiffening board), koshi-himo (waist cords), date-jime (another belt under the obi), tabi (split-toe socks), and zori (sandals). And that's the simplified version.

The staff dressed me in layers I couldn't name while I stood there like a mannequin learning what it means to be wrapped in intention.

My outfit was a haori—a hip-length jacket—worn over a patterned kimono. Grey, with wagon-wheel motifs called waguruma. The haori dates back to the Sengoku period (1467-1615), when samurai wore them over armor in winter campaigns. By the Edo period, wealthy merchants began wearing haori with deliberately plain exteriors but lavishly decorated linings—a quiet rebellion against laws that restricted their clothing based on social class.

They could afford silk. They just couldn't show it.

Historical fact: The haori I wore would have been illegal for a common citizen to wear during the Tokugawa shogunate. Only samurai and nobility had the right to this garment. Later, geisha in Tokyo's Fukagawa district broke this tradition around 1800, wearing haori as a fashion statement—and started a trend that took 130 years to fully catch on with women.

The Weight of Silk

The women with me wore something heavier.

Traditional furisode-style kimonos with patterns that seemed to move even when they stood still—yellow flowers against indigo, white magnolias tumbling across navy blue. The obi alone—that wide decorative belt—can weigh several pounds when made of proper silk brocade. Some formal obi are 4 meters long.

What strikes you is the posture it creates. You don't slouch in a kimono. You can't. The structure holds you upright, transforms your walk into something more deliberate. There's a reason the Japanese word kikonashi—meaning the way one wears clothes—is considered an art form.

The price of tradition: An authentic silk kimono with custom dyeing (called yuzen, a technique from the Edo period involving hand-painted resist dyeing) can cost anywhere from $10,000 to over $100,000. What we wore were rentals—beautiful, but democratized versions of something that was once reserved for weddings, tea ceremonies, and the aristocracy.

A Garden That Isn't a Garden

The photo location was a bamboo garden in Tokyo—compressed, curated, perfect.

It had everything: moso bamboo arranged in a half-fence pattern, a sculpted pine (probably decades old), stone paths, and that red torii marking the entrance to a space that doesn't technically exist.

Here's what I mean: Japanese garden design is based on shakkei—"borrowed scenery." The idea that a garden should frame views beyond its boundaries, incorporating distant mountains or forests as part of its composition. But in urban Tokyo, there are no distant mountains. So these rental studios create contained worlds—gardens that exist entirely for the photograph, for the memory, for the three hours you spend pretending you're somewhere that time forgot.

The torii in this garden served no religious function. It was symbol stripped of context, made beautiful, made consumable.

And I don't know how to feel about that.

Why We Do This

More than 3 million tourists rent kimonos in Kyoto alone each year. Tokyo's numbers are harder to pin down, but the industry has exploded—driven partly by Instagram, partly by a genuine desire to touch something older than ourselves.

The Japanese have a word: furugi—old clothes. But more specifically, they have a phrase: mottainai—roughly, "what a waste." It captures the sadness of throwing away something that still has value. Kimono rental shops are, in a way, fighting mottainai. They're keeping these garments in circulation, on bodies, in photographs, in some version of living use.

Is it authentic? Probably not.

Is it appropriation? The staff seemed genuinely delighted to dress us. They adjusted my collar three times to get it right. They taught me how to hold my hands (together, in front, fingers hidden). They told me I looked kakkoi—cool.

What I think is this: every tradition was once an innovation. The haori was once controversial. The red torii was borrowed from Buddhism, which borrowed it from Indian torana gates. Culture is a river. You can step into it or watch from the shore.

The Photo

The three of us stood there—me in grey, them in explosions of color—inside a room with tatami mats and gold-threaded screens.

For a moment, we weren't tourists. We weren't playing dress-up. We were people standing in clothes that other people made with their hands, using techniques passed down through generations, wearing patterns that meant something to someone, somewhere, sometime.

Then we took our phones out and snapped the shot.

What Stays

I kept the tabi socks. Split-toed, white cotton, designed for a sandal I'll never wear again.

They sit in my drawer now, next to regular socks. Every few months I see them and remember:

The weight of the obi.
The sound of zori on stone.
The way the bamboo smelled.
The red gate marking passage into somewhere I couldn't stay.

Torii translates literally as "bird perch." According to Japanese mythology, the first torii was built to lure the sun goddess Amaterasu out of a cave where she'd been hiding—they placed roosters on a wooden perch, hoping their crowing would draw her curiosity.

It worked. She came out. The world had light again.

Some gates are meant to be walked through. Others are meant to remind you that the crossing was possible.

Tokyo, September 2024

Quick Facts

• Kimono rental cost: ¥3,000-10,000 (~$20-70 USD) for basic packages; premium experiences with photography can exceed ¥50,000
• Dressing time: 20-45 minutes depending on complexity
• Haori history: Originally samurai and nobility-only garment from 1500s; women began wearing them around 1800
• Torii gates in Japan: Approximately 90,000+ across Shinto shrines nationwide
• Torii color meaning: Red (vermillion) represents vitality, protection from evil spirits, and the sun's life-giving energy

What You’ll Learn in This Chapter

By now, you have:

• A working FastAPI app scaffold from Lesson 1
• A clean environment and Docker setup from Lesson 2

In this chapter, we’ll:

• Structure the app for modularity
• Organize routes into versioned modules
• Implement shared dependencies
• Prepare the app for future features (auth, databases, Kafka) without rewriting core logic

By the end, you’ll have a production-ready FastAPI skeleton that’s easy to extend for any microservice.

Why Structure Matters in FastAPI

FastAPI is flexible, but if you throw all routes into main.py, your project will:

• Get messy quickly
• Make it harder to reuse code
• Slow down onboarding for new devs

We’ll fix that by:

• Grouping routes into versioned modules
• Using dependency injection for reusability
• Keeping main.py minimal (just an app factory)

Folder Structure Update

We’ll refine from Lesson 2 to introduce domain-driven structure:

app/
├─ api/
│  ├─ deps.py                 # Shared dependencies
│  ├─ v1/
│  │  ├─ __init__.py
│  │  ├─ routes_health.py     # System health/version
│  │  ├─ routes_users.py      # Example resource
│  │  └─ routes_items.py      # Example resource
├─ core/
│  ├─ config.py
│  ├─ logging.py
│  ├─ version.py
├─ domain/                    # Business logic
│  ├─ users.py
│  └─ items.py
├─ ports/
├─ adapters/
└─ main.py

Step-by-Step Build

1. Shared Dependencies

Dependencies help avoid repetitive code like DB connections or auth checks.

app/api/deps.py

from fastapi import Depends

# Example: current user dependency placeholder
def get_current_user():
    return {"username": "demo_user"}

2. Routes by Feature

We’ll create an example resource to show modularity.

app/api/v1/routes_users.py

from fastapi import APIRouter, Depends
from app.api.deps import get_current_user

router = APIRouter()

@router.get("/users/me", tags=["users"])
async def read_current_user(current_user: dict = Depends(get_current_user)):
    return current_user

app/api/v1/routes_items.py

from fastapi import APIRouter

router = APIRouter()

@router.get("/items", tags=["items"])
async def list_items():
    return [{"id": 1, "name": "Example Item"}]

3. API Router Assembly

We’ll gather all v1 routes in a single file for cleaner main.py.

app/api/v1/init.py

from fastapi import APIRouter
from .routes_health import router as health_router
from .routes_users import router as users_router
from .routes_items import router as items_router

api_router = APIRouter()
api_router.include_router(health_router)
api_router.include_router(users_router)
api_router.include_router(items_router)

4. Clean main.py

Your main.py now just wires settings, logging, and routes.

app/main.py

from fastapi import FastAPI
from app.core.config import settings
from app.core.logging import setup_logging
from app.api.v1 import api_router

def create_app() -> FastAPI:
    setup_logging(settings.log_level)

    app = FastAPI(
        title=settings.app_name,
        version="0.1.0",
        docs_url="/docs",
        redoc_url="/redoc",
    )

    app.include_router(api_router, prefix=settings.api_v1_str)

    return app

app = create_app()

5. Test It

Run locally:

poetry run uvicorn app.main:app --reload

Test endpoints:

curl http://127.0.0.1:8000/api/v1/health
curl http://127.0.0.1:8000/api/v1/users/me
curl http://127.0.0.1:8000/api/v1/items

Checklist for Chapter 3 Completion

• api/v1 folder contains separate route files for each feature
• deps.py created for shared dependencies
• api_router collects all routes into one import for main.py
• main.py contains no business logic — just app wiring
• App runs and all endpoints respond correctly

Next Up – Lesson 4

In FastAPI Blueprint 04: Database Layer Abstraction, we’ll:

• Implement a generic database port interface
• Create adapters for PostgreSQL, MongoDB, and Redis
• Show how to switch DBs via config, even run multiple in one service

What you will learn

• What this series builds and why
• How the template is structured so you can reuse it for auth, sales, reports, or social feeds
• The roles of PostgreSQL, MongoDB, Redis, and Kafka in this architecture
• A ready starter project with FastAPI, typed settings, basic logging, versioned routing, and a health endpoint

Why microservices for this template

We want a template that can be reused for different domains without copy paste chaos. A microservice works well when you keep boundaries clear and communication explicit. You get independent deploys, tech freedom per service, and the ability to scale hot paths only.

Tradeoffs to accept:

• More moving parts
• You need good observability and testing
• Data consistency requires care

High level architecture

[Client or Another Service]
            |
        HTTP/REST
            v
     +-----------------+
     |  FastAPI App    |
     |  Routers        |
     |  DI glue        |
     +--------+--------+
              | Service layer calls ports
    +---------+-----------------------------+
    |                                       |
[Database Ports]                      [Messaging Port]
  |        |        |                       |
Postgres  MongoDB  Redis                 Kafka Client

• Routers expose HTTP endpoints
• Service layer holds use cases and rules
• Ports define interfaces for infrastructure
• Adapters implement those ports for Postgres, MongoDB, Redis, Kafka

This is the clean architecture vibe. Business code depends on interfaces, not concrete tech. You can swap a datastore or add one without rewriting your core logic.

When to use each datastore

• PostgreSQL: transactional data, strong consistency, relations
• MongoDB: flexible documents, analytics-style reads, content feeds
• Redis: caching, sessions, rate limits, short lived data
• Kafka: events between services, decoupling write and read models

You can use more than one in the same service. Example: write orders in Postgres, cache summaries in Redis, publish order events to Kafka.

What we build today

• Project scaffold that will scale for the rest of the series
• App factory with typed settings
• Versioned API prefix
• Health and version endpoints
• Logging that plays nice in containers
• Placeholders for databases and Kafka that we will fill later

Code for Step 1

Folder tree

fastapi-blueprint/
├─ pyproject.toml                 # or requirements.txt if you prefer pip
├─ README.md
├─ .env.example
├─ .gitignore
├─ Dockerfile
├─ app/
│  ├─ __init__.py
│  ├─ core/
│  │  ├─ config.py               # Pydantic settings
│  │  ├─ logging.py              # base logging setup
│  │  └─ version.py              # service version
│  ├─ main.py                    # app factory
│  ├─ api/
│  │  ├─ __init__.py
│  │  ├─ deps.py                 # shared dependencies
│  │  ├─ v1/
│  │  │  ├─ __init__.py
│  │  │  └─ routes_health.py     # /health, /version
│  ├─ domain/                    # business rules later
│  │  └─ __init__.py
│  ├─ ports/                     # interfaces
│  │  ├─ __init__.py
│  │  ├─ db_port.py
│  │  └─ messaging_port.py
│  └─ adapters/                  # implementations later
│     ├─ __init__.py
│     ├─ postgres_adapter.py
│     ├─ mongodb_adapter.py
│     ├─ redis_adapter.py
│     └─ kafka_adapter.py
└─ tests/
   └─ test_health.py

pyproject.toml (Poetry)

If you prefer pip, I include a requirements.txt right after.

[tool.poetry]
name = "fastapi-blueprint"
version = "0.1.0"
description = "FastAPI microservice template - Step 1 scaffold"
authors = ["You <you@example.com>"]
readme = "README.md"
packages = [{ include = "app" }]

[tool.poetry.dependencies]
python = "^3.12"
fastapi = "^0.115.0"
uvicorn = { extras = ["standard"], version = "^0.30.0" }
pydantic-settings = "^2.4.0"

[tool.poetry.group.dev.dependencies]
pytest = "^8.3.0"
httpx = "^0.27.0"
pytest-asyncio = "^0.23.7"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

requirements.txt (pip alternative)

fastapi==0.115.0
uvicorn[standard]==0.30.0
pydantic-settings==2.4.0
pytest==8.3.0
httpx==0.27.0
pytest-asyncio==0.23.7

.env.example

APP_NAME=fastapi-blueprint
APP_ENV=local
API_V1_STR=/api/v1
LOG_LEVEL=INFO

app/core/version.py

SERVICE_NAME = "fastapi-blueprint"
SERVICE_VERSION = "0.1.0"

app/core/config.py

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    app_name: str = "fastapi-blueprint"
    app_env: str = "local"
    api_v1_str: str = "/api/v1"
    log_level: str = "INFO"

    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")

settings = Settings()

app/core/logging.py

import logging
import sys

def setup_logging(level: str = "INFO") -> None:
    handler = logging.StreamHandler(sys.stdout)
    fmt = "%(asctime)s | %(levelname)s | %(name)s | %(message)s"
    handler.setFormatter(logging.Formatter(fmt))
    root = logging.getLogger()
    root.handlers.clear()
    root.addHandler(handler)
    root.setLevel(level.upper())

app/api/v1/routes_health.py

from fastapi import APIRouter
from app.core.version import SERVICE_NAME, SERVICE_VERSION

router = APIRouter()

@router.get("/health", tags=["system"])
async def health() -> dict:
    return {"status": "ok"}

@router.get("/version", tags=["system"])
async def version() -> dict:
    return {"service": SERVICE_NAME, "version": SERVICE_VERSION}

app/api/deps.py

# Shared dependencies live here. Example:
# from fastapi import Depends
# def get_current_user(...) -> User: ...

app/ports/db_port.py

from typing import Protocol, Any

class DatabasePort(Protocol):
    async def connect(self) -> None: ...
    async def close(self) -> None: ...
    # You can add generic methods or keep it minimal for now

app/ports/messaging_port.py

from typing import Protocol, Mapping, Any

class MessagingPort(Protocol):
    async def publish(self, topic: str, key: bytes | None, value: bytes, headers: Mapping[str, bytes] | None = None) -> None: ...
    async def start_consumer(self) -> None: ...
    async def stop_consumer(self) -> None: ...

app/adapters placeholders

# app/adapters/postgres_adapter.py
# Implement DatabasePort for Postgres in a later lesson

# app/adapters/mongodb_adapter.py
# Implement DatabasePort for MongoDB in a later lesson

# app/adapters/redis_adapter.py
# Implement DatabasePort for Redis in a later lesson

# app/adapters/kafka_adapter.py
# Implement MessagingPort for Kafka in a later lesson

app/main.py

from fastapi import FastAPI
from app.core.config import settings
from app.core.logging import setup_logging
from app.api.v1.routes_health import router as health_router

def create_app() -> FastAPI:
    setup_logging(settings.log_level)

    app = FastAPI(
        title=settings.app_name,
        version="0.1.0",
        docs_url="/docs",
        redoc_url="/redoc",
    )

    # Versioned API
    app.include_router(health_router, prefix=settings.api_v1_str)

    @app.get("/", tags=["system"])
    async def root():
        return {"message": "Service running", "name": settings.app_name}

    return app

app = create_app()

tests/test_health.py

import pytest
from httpx import AsyncClient
from app.main import create_app

@pytest.mark.asyncio
async def test_health():
    app = create_app()
    async with AsyncClient(app=app, base_url="http://test") as ac:
        resp = await ac.get("/api/v1/health")
    assert resp.status_code == 200
    assert resp.json()["status"] == "ok"

Dockerfile

FROM python:3.12-slim

WORKDIR /app

# If you use Poetry
RUN pip install --no-cache-dir poetry==1.8.3
COPY pyproject.toml poetry.lock* /app/
RUN poetry config virtualenvs.create false \
  && poetry install --no-interaction --no-ansi

# If you use pip instead, comment out the Poetry block above and:
# COPY requirements.txt /app/
# RUN pip install --no-cache-dir -r requirements.txt

COPY . /app

ENV PYTHONUNBUFFERED=1
ENV PORT=8080

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080"]

Quick start

Using Poetry:

poetry install
cp .env.example .env
poetry run uvicorn app.main:app --reload

Using pip:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload

Test it:

curl http://127.0.0.1:8000/api/v1/health
curl http://127.0.0.1:8000/api/v1/version

You now have a clean skeleton that we can extend in the next lessons. Step 2 will set up the full project environment, refine config handling, and lock in the folder conventions so adding databases and Kafka later feels natural.

Want me to drop this into a Ghost-ready post file and a GitHub README, or generate a zip so you can download the scaffold in one shot?

What You’ll Learn in This Chapter

In the first chapter, we mapped out the architecture for our FastAPI microservice template.
Now it’s time to lay the foundation — the project’s environment and folder structure — so everything is clean, consistent, and easy to extend.

By the end of this chapter, you’ll have:

• A consistent folder structure for your service
• Poetry or pip configured with dependencies
• Environment variable management with .env and Pydantic Settings
• A running FastAPI app with a /health endpoint from Step 1
• Ready-to-use Docker setup for containerized development

Why Environment Setup Matters

A microservice template isn’t just about code — it’s about maintainability.
A good setup should let you:

• Onboard a new developer in minutes
• Swap databases or message brokers without changing core logic
• Keep configs out of your codebase and in .env files or secret managers
• Run locally with minimal fuss, whether via uvicorn or Docker

Skipping this step means your “template” quickly turns into spaghetti that’s hard to reuse.

Folder Structure We’ll Use

We’ll extend the structure from Step 1:

fastapi-blueprint/
├─ pyproject.toml / requirements.txt
├─ .env.example
├─ Dockerfile
├─ docker-compose.yml   <-- added here for local DB/message broker runs
├─ app/
│  ├─ core/             <-- config, logging, constants
│  ├─ api/              <-- versioned routes
│  ├─ domain/           <-- business logic
│  ├─ ports/            <-- interfaces
│  ├─ adapters/         <-- implementations
│  └─ main.py
└─ tests/

Step-by-Step Setup

1. Choose Dependency Manager

We’ll use Poetry in this series, but I’ll include pip equivalents.
Poetry gives you lock files and a cleaner dependency setup.

Poetry:

pip install poetry
poetry init
poetry add fastapi uvicorn[standard] pydantic-settings
poetry add --group dev pytest httpx pytest-asyncio

Pip:

python -m venv .venv
source .venv/bin/activate
pip install fastapi uvicorn[standard] pydantic-settings pytest httpx pytest-asyncio
pip freeze > requirements.txt

2. Create .env and .env.example

We’ll define default configs here:

.env.example

APP_NAME=fastapi-blueprint
APP_ENV=local
API_V1_STR=/api/v1
LOG_LEVEL=INFO

Copy it to .env for local runs:

cp .env.example .env

3. Configure Pydantic Settings

app/core/config.py

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    app_name: str
    app_env: str
    api_v1_str: str
    log_level: str = "INFO"

    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")

settings = Settings()

4. Update Main App Factory

We’ll extend Step 1’s create_app() to load settings automatically:

app/main.py

from fastapi import FastAPI
from app.core.config import settings
from app.core.logging import setup_logging
from app.api.v1.routes_health import router as health_router

def create_app() -> FastAPI:
    setup_logging(settings.log_level)

    app = FastAPI(
        title=settings.app_name,
        version="0.1.0",
        docs_url="/docs",
        redoc_url="/redoc",
    )

    app.include_router(health_router, prefix=settings.api_v1_str)

    return app

app = create_app()

5. Add Docker Support

Dockerfile (from Step 1) stays mostly the same, but now we add Compose.

docker-compose.yml

version: '3.9'

services:
  app:
    build: .
    container_name: fastapi_blueprint
    ports:
      - "8000:8000"
    env_file: .env
    volumes:
      - .:/app
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

6. Test the Setup

Run locally:

poetry run uvicorn app.main:app --reload

or via Docker:

docker compose up --build

Check:

curl http://127.0.0.1:8000/api/v1/health

What’s Next (Step 3 Preview)

In FastAPI Blueprint 03: Core FastAPI Structure, we’ll:

• Break routes into modules
• Introduce dependency injection for shared logic
• Set up API versioning conventions for long-term growth

✅ Checklist for Chapter 2 Completion

• Poetry or pip installed and configured
• .env and .env.example created
• Settings class reads environment variables
• App loads configs and logging from .env
• Dockerfile + docker-compose.yml tested locally
• /health endpoint reachable at http://localhost:8000/api/v1/health

If you want, I can now generate the matching “Step 2” feature image with the same blueprint background as Step 1, but updated to say:
FastAPI Blueprint 02: Project Setup & Environment
That way your series stays visually consistent.

Do you want me to make it?

Ever juggled code across personal, work, and side-project accounts only to push with the wrong credentials? In this post you’ll build a two-script toolkit that solves the problem:

1. generate_ssh_key.sh – creates a fresh SSH key and drops a ready-to-paste stanza into ~/.ssh/config.
2. checkout – rewrites any Git URL so git clone automatically uses the right key for that host.

Along the way you’ll:

• Organize your scripts in a dedicated directory
• Add that directory to PATH
• Test the flow end-to-end

Why bother with per-repo keys?

• Security – revoke a single key without touching other repos.
• Separation of concerns – clean audit trails for each Git hosting account.
• Convenience – eliminate GIT_SSH_COMMAND hacks or accidental pushes with the wrong identity.

Project layout

~/Development/personal/innovate-hub/tools/scripts/
│
├── generate_ssh_key.sh  # script 1
└── checkout             # script 2  (no .sh for nicer UX)

Make sure the directory exists:

mkdir -p ~/Development/personal/innovate-hub/tools/scripts

Script 1 – generate_ssh_key.sh

#!/usr/bin/env bash
# Usage: generate_ssh_key.sh <key-name>

set -euo pipefail

if [[ -z "${1-}" ]]; then
  echo "Usage: $0 <key_name>"; exit 1
fi

KEY_NAME="$1"
SSH_DIR="$HOME/.ssh"
KEY_PATH="$SSH_DIR/id_rsa_${KEY_NAME}"

if [[ -f "$KEY_PATH" ]]; then
  echo "Key ${KEY_NAME} already exists at ${KEY_PATH}"; exit 1
fi

mkdir -p "$SSH_DIR" && chmod 700 "$SSH_DIR"

ssh-keygen -t rsa -b 4096 -f "${KEY_PATH}" -N "" -C "${KEY_NAME}@$(hostname)"

cat <<EOF

# ─── Add this to ~/.ssh/config ────────────────────────────────────────────────
Host ${KEY_NAME}
  HostName github.com            # or gitlab.com, bitbucket.org, etc.
  User git
  IdentityFile ${KEY_PATH}
  IdentitiesOnly yes
# ──────────────────────────────────────────────────────────────────────────────

Public key (paste into your Git provider):
$(cat "${KEY_PATH}.pub")
EOF

What it does

• Bails if no key name is provided.
• Generates id_rsa_<key> with a 4096-bit key size.
• Prints a ready-made Host block so you never mistype paths in ssh_config.

Script 2 – checkout

#!/usr/bin/env bash
# Usage: checkout <git-url>
# Example: checkout https://github.com/kiarash/my-repo.git
#          checkout git@gitlab.com:kiarash/secret.git

set -euo pipefail

URL="${1-}"
[[ -z "$URL" ]] && { echo "Usage: $0 <git-url>"; exit 1; }

CONFIG="$HOME/.ssh/config"

# Extract hostname and repo path
if [[ "$URL" =~ ^git@([^:]+):(.+)$ ]]; then
  HOST="${BASH_REMATCH[1]}"
  PATH_PART="${BASH_REMATCH[2]}"
elif [[ "$URL" =~ ^https?://([^/]+)/(.+)$ ]]; then
  HOST="${BASH_REMATCH[1]}"
  PATH_PART="${BASH_REMATCH[2]}"
else
  echo "Unrecognised URL: $URL"; exit 1
fi

# Find matching Host alias in ~/.ssh/config
ALIAS=$(awk -v h="$HOST" '
  $1=="Host"   {host=$2}
  $1=="HostName" && $2==h {print host}
' "$CONFIG")

[[ -z "$ALIAS" ]] && { echo "No Host entry for ${HOST}"; exit 1; }

NEW_URL="git@${ALIAS}:${PATH_PART}"
echo "Cloning with ${NEW_URL}"
git clone "${NEW_URL}"

What it does

1. Parses the incoming URL (SSH or HTTPS).
2. Looks up a HostName match inside ~/.ssh/config.
3. Rewrites the URL to git@<Host-alias>:repo/path.git.
4. Runs git clone so the correct key is automatically selected.

Make the scripts executable

chmod +x ~/Development/personal/innovate-hub/tools/scripts/{generate_ssh_key.sh,checkout}

Add the scripts directory to PATH

Edit ~/.zshrc (or ~/.profile if you prefer it shell-agnostic):

export PATH="$PATH:$HOME/Development/personal/innovate-hub/tools/scripts"

Then reload:

source ~/.zshrc   # or source ~/.profile

Confirm:

which checkout
# → /home/kevin/Development/personal/innovate-hub/tools/scripts/checkout

Putting it all together

1. Work as usual – all future git pull/push operations in that repo use the linked key.

Clone using the smart checkout:

cd ~/code
checkout https://github.com/kiarash/my-repo.git

The script maps github-personal, rewrites the URL, and clones with the right key.

Generate a key per account or repo:

generate_ssh_key.sh github-personal

Paste the public key into GitHub and add the printed block to ~/.ssh/config.

Troubleshooting

Happy cloning – and no more mismatched keys!

To publish the guide on your Ghost blog with all the necessary formatting, you can copy and paste the text below directly into the Ghost editor. The markdown headings, lists, and bold text are already included.

How to Add Google Tag Manager to Your Ghost Blog

Are you looking to get more out of your Ghost blog? Implementing Google Tag Manager (GTM) is a fantastic way to track your audience's behavior, manage third-party scripts, and supercharge your analytics—all without constantly editing your theme files.

The good news is, adding GTM to a Ghost site is a straightforward process, thanks to the platform's built-in Code Injection feature. Here’s a simple, step-by-step guide to get you up and running.

Step 1: Grab Your GTM Code Snippets

First, you'll need to create a Google Tag Manager account and a new container for your blog if you haven't already. Once that's done, GTM will provide you with two unique code snippets:

1. A <head> snippet, which should be placed as high as possible in the <head> section of your site.
2. A <body> snippet, which needs to be placed immediately after the opening <body> tag.

Keep these two snippets handy, as you'll be using them in the next step.

Step 2: Use Ghost's Code Injection

Ghost’s admin dashboard has a powerful feature for adding custom code without touching the theme's core files. This is exactly what we'll use for GTM.

1. Log into your Ghost admin dashboard.
2. In the left-hand menu, click on Settings.
3. Scroll down to the Advanced section and select Code Injection.

You'll see two text areas: Site Header and Site Footer.

• For the <head> snippet: Copy the first GTM code snippet and paste it into the Site Header field. This ensures the code is loaded on every page, just before the closing </head> tag.
• For the <body> snippet: While GTM recommends placing this snippet immediately after the opening <body> tag, Ghost's Code Injection feature only provides a Site Footer field, which places code right before the closing </body> tag. This is a standard and acceptable workaround for Ghost users. Simply paste the second GTM code snippet into the Site Footer field.

4. Click the Save button in the top-right corner.

Step 3: Verify Your Installation with Tag Assistant

After saving your changes, it's essential to make sure everything is working correctly.

1. Go back to your Google Tag Manager workspace.
2. Click the Preview button.
3. A new window will pop up. Enter the URL of your Ghost blog and click Connect.

This will open your website in a new tab with the Tag Assistant debug console at the bottom of the screen. If you see your container ID listed and the status shows "Connected," you've successfully installed Google Tag Manager on your Ghost blog. You can now start adding and managing all your tags, triggers, and variables directly from the GTM interface.

🚀 How to Install pyenv on Ubuntu (The Easy Way)

If you’ve ever juggled multiple Python versions on your machine and felt the pain of dependency conflicts, pyenv is your new best friend. It's a simple yet powerful tool that allows you to install and manage multiple Python versions on the same system without headaches.

In this guide, I’ll walk you through how to install pyenv on Ubuntu step by step. Whether you're a beginner or a seasoned developer, this will help you get started quickly and cleanly.

🧰 What is pyenv and Why Should You Use It?

pyenv lets you easily:

• Install multiple versions of Python side-by-side
• Switch Python versions globally or per-project
• Create isolated environments (with pyenv-virtualenv)

This is especially useful if you're working on different projects that require different Python versions.

🛠️ Step 1: Install Required Dependencies

Before installing pyenv, make sure your system has the necessary build tools and libraries:

sudo apt update
sudo apt install -y make build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev \
libffi-dev liblzma-dev git

These packages are essential for compiling and running different versions of Python from source.

📥 Step 2: Install pyenv via Curl

Use the official installation script to install pyenv and its plugins:

curl https://pyenv.run | bash

This will install:

• pyenv
• pyenv-virtualenv (for managing virtual environments)
• pyenv-update (for keeping it up-to-date)
• pyenv-doctor (for troubleshooting)

🧠 Step 3: Add pyenv to Your Shell

Now, we need to let your shell know about pyenv. Add the following lines to your shell configuration file.

If you use bash:

nano ~/.bashrc

Add this at the end of the file:

export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

Then reload your shell:

source ~/.bashrc

If you use zsh:

Do the same in ~/.zshrc, and run:

source ~/.zshrc

✅ Step 4: Verify the Installation

You’re almost done! To make sure everything is working, run:

pyenv --version

You should see the installed version of pyenv. If that works, you’re ready to start installing Python versions.

🐍 Step 5: Install a Python Version

Let’s install Python 3.12.2 as an example:

pyenv install 3.12.2

Once installed, set it as the global (default) Python version:

pyenv global 3.12.2

You can confirm it with:

python --version

📦 Bonus: Create a Virtual Environment

Want an isolated environment for a project?

pyenv virtualenv 3.12.2 myenv
pyenv activate myenv

Now you can install packages without affecting your system Python.

💡 Final Thoughts

Managing Python versions doesn’t have to be messy. pyenv gives you clean control over your development environment, especially when working across projects with different dependencies.

If you're working on Ubuntu, this setup will save you time and headaches in the long run. Once you’ve got pyenv running, pair it with tools like poetry or pip-tools to take your Python workflow to the next level.

Got questions? Drop them in the comments — I’m happy to help.

The fluorescent lights hummed overhead in the San Francisco jury assembly room, casting that particular institutional glow that makes everyone look slightly unwell. Around me, nearly 200 people sat in rigid plastic chairs, summoned by civic duty to this windowless room in the Hall of Justice. It should have been a fascinating social experiment—a true cross-section of the city forced together for hours with nothing but time.

Instead, it felt like sitting in a library of ghosts.

I counted the interactions during my first hour: a woman asked someone to watch her purse while she used the restroom. A man inquired about the WiFi password. That was it. Two conversations among two hundred people.

The rest of us existed in our own digital bubbles, necks craned downward in what chiropractors have dubbed "text neck," fingers scrolling through endless feeds of other people's lives while ignoring the actual lives sitting eighteen inches away. We had become experts at being alone together.

The Great Divide

What struck me most wasn't the silence itself, but the clear generational fault line running through the room. The older citizens—those who remembered life before smartphones became appendages—were the ones attempting eye contact. They looked around with the patience of people accustomed to waiting without entertainment, occasionally offering shy smiles or commenting on the proceedings.

A woman in her seventies near me kept glancing hopefully at her neighbors, clearly ready for conversation. She reminded me of my grandmother, who could strike up a meaningful chat with a stranger at the grocery store checkout line. But her potential conversation partners were busy photographing their jury summons for Instagram stories or catching up on work emails.

I watched one man, probably in his sixties, try three separate times to make small talk with people around him. Each attempt was met with polite but brief responses before his intended conversation partners returned to their screens. Eventually, he gave up and stared at the informational posters on the wall with the resigned attention of someone studying for a test.

The Irony of Civic Isolation

There's something deeply ironic about this scene. Jury duty represents one of our most fundamental civic responsibilities—the idea that ordinary citizens can come together, listen to evidence, and make fair decisions that affect real lives. It's predicated on our ability to connect with and understand our fellow humans, to see past our own biases and experiences.

Yet here we were, practicing isolation before we'd even reached the courtroom.

The orientation video played to a room full of people barely watching. It explained the importance of avoiding bias, of listening carefully, of considering different perspectives. But how can we practice those skills if we can't even make eye contact with the person next to us? How do we build the empathy muscles required for fair deliberation when we've forgotten how to engage with strangers?

What We've Lost

I found myself mourning something I'd never experienced: the jury duty of previous generations. I imagined rooms where people actually talked—where a retired teacher might chat with a construction worker about their kids' schools, where a recent immigrant might share stories with a fourth-generation San Franciscan, where the kind of casual "nosiness" that builds community bonds would naturally emerge.

That nosiness wasn't just idle curiosity—it was practice. Practice at being interested in people different from ourselves. Practice at finding common ground with strangers. Practice at the fundamental human skill of connection that democracy requires.

Instead, we've created a society where the default response to uncomfortable silence or unfamiliar people is to retreat into our devices. We've become so accustomed to curated connection—choosing exactly who we interact with and when—that random human contact feels almost invasive.

The Digital Comfort Zone

Our phones have become emotional support objects, providing instant escape from the mild anxiety of being present with strangers. Why make awkward small talk when you can scroll through TikTok? Why wonder about the person next to you when you can catch up with friends on WhatsApp? Why sit with the discomfort of silence when Netflix has episodes downloaded and ready?

But in choosing comfort, we've lost something essential. Those uncomfortable moments of waiting, of not knowing what to say, of reaching across difference—those are exactly the moments where empathy grows. They're the social equivalent of physical exercise: mildly unpleasant but ultimately strengthening.

The Older Generation's Gift

Watching the older jurors reminded me that this withdrawal isn't inevitable—it's learned. These were people who remembered when waiting rooms were places of conversation, when delayed flights meant talking to fellow passengers, when being bored together was an opportunity rather than a problem to solve with technology.

One elderly man eventually started reading a physical newspaper, and I noticed how it became a conversation starter. People could see what he was reading, comment on headlines, ask questions. His newspaper was public in a way our private screens never are. It invited engagement rather than signaling unavailability.

What We're Teaching Our Juries

As I sat there, I couldn't help but wonder: what kind of jurors are we creating in this age of digital isolation? If we can't practice the basic human skill of talking to strangers in a waiting room, how do we suddenly develop the ability to engage meaningfully in a jury room?

The skills are the same: listening to people different from ourselves, managing discomfort and uncertainty, staying present when things get awkward or difficult, finding common ground despite obvious differences. But we're out of practice. We've forgotten how to be curious about each other.

The Path Back

I'm not advocating for throwing our phones in the trash or returning to some imaginary golden age. But I am suggesting that we've lost something valuable in our rush toward digital connection, and spaces like jury duty waiting rooms reveal the cost.

Maybe the solution starts small. Maybe it's as simple as looking up more often, making eye contact, asking someone how their day is going. Maybe it's remembering that the person next to us has a story worth hearing, problems worth understanding, perspectives worth considering.

Maybe it's recognizing that our civic duty begins not in the courtroom, but in the waiting room—with the simple, radical act of seeing each other as more than just fellow screen-gazers.

Because if we can't connect over the shared experience of jury duty, how can we expect to connect over the shared experience of democracy? And if we can't practice empathy with the stranger sitting next to us, how can we practice it with the defendant whose fate might rest in our hands?

The fluorescent lights continued to hum. Around me, 200 people continued to scroll. But for the first time that morning, I put my phone away and looked around—really looked—at my fellow citizens. Some of them, I noticed, were looking back.

🔍 Why this guide?

Running a mixed‑GPU desktop (USB‑based DisplayLink adapters plus an NVIDIA® GeForce card) on Ubuntu is incredibly powerful—but it can be tricky.
Common headaches include:

• Monitors that randomly reorder after every reboot.
• DisplayLink screens not waking from sleep.
• “Unknown display” errors in Settings → Displays.

This post walks you through a bullet‑proof, script‑driven workflow that:

1. Installs the correct drivers.
2. Restores your preferred layout automatically at login.
3. Fixes the most common pitfalls.

Table of Contents 

1. Prerequisites & Hardware
2. Step 1 — Install / Clean DisplayLink Drivers
3. Step 2 — Map Your Monitors with xrandr
4. Step 3 — Create an Auto‑Layout Script
5. Step 4 — Run the Script at Startup
6. Troubleshooting & FAQs
7. Power‑User Tips
8. SEO Resources & Further Reading

1. Prerequisites & Hardware Checklist 

Tip: Always remove older EVDI DKMS packages before installing a new DisplayLink build:
sudo dkms remove evdi/<version> --all

2. Step 1 — Install / Clean DisplayLink Drivers ⚙️ 

Reboot & verify

systemctl status displaylink-driver
lsusb | grep -i displaylink

Install DisplayLink official package

unzip DisplayLink*Ubuntu*.zip
cd DisplayLink*
sudo ./displaylink-installer.sh install

Purge conflicting EVDI builds

sudo apt purge evdi-dkms
sudo dkms status  # ensure nothing is left

If the service is active and your USB device appears, you’re good to go.

3. Step 2 — Map Your Monitors with xrandr 

Run:

xrandr --listmonitors

Sample output:

Monitors: 4
 0: +*HDMI-1 1920/526x1080/296+1920+1080  HDMI-1
 1: +HDMI-0 1920/526x1080/296+0+1080     HDMI-0
 2: +DVI-I-3-1 1920/526x1080/296+0+0     DVI-I-3-1
 3: +DVI-I-4-2 1920/526x1080/296+1920+0  DVI-I-4-2

Interpretation:

• Top row: DVI-I-3-1 (left), DVI-I-4-2 (right)
• Bottom row: HDMI-0 (left), HDMI-1 (right & primary)

Got different names? Copy yours exactly—they can change from PC to PC.

4. Step 3 — Create an Auto‑Layout Script 📝 

Create the script:

mkdir -p ~/.config
nano ~/.config/set-monitor-layout.sh

Paste & edit as needed:

#!/bin/bash
# —— Fix monitor order for DisplayLink + NVIDIA ——

xrandr \
  --output DVI-I-3-1 --mode 1920x1080 --pos 0x0     --rotate normal \
  --output DVI-I-4-2 --mode 1920x1080 --pos 1920x0  --rotate normal \
  --output HDMI-1    --mode 1920x1080 --pos 0x1080  --rotate normal \
  --output HDMI-0    --primary --mode 1920x1080 --pos 1920x1080 --rotate normal

Make it executable:

chmod +x ~/.config/set-monitor-layout.sh

Test:

~/.config/set-monitor-layout.sh

Your screens should snap into the saved layout.

5. Step 4 — Run the Script at Startup 🚀 

GNOME & most DEs use ~/.config/autostart/.

mkdir -p ~/.config/autostart
nano ~/.config/autostart/set-monitor-layout.desktop

Insert:

[Desktop Entry]
Type=Application
Exec=bash -c "sleep 7 && /home/$USER/.config/set-monitor-layout.sh"
Hidden=false
NoDisplay=false
X-GNOME-Autostart-enabled=true
Name=Set Monitor Layout

Why the sleep 7? DisplayLink needs a few seconds to initialize after login.

Reboot and watch the magic happen. ✅

6. Troubleshooting & FAQs 🔧 

7. Power‑User Tips ⚡️ 

• Toggle scripts: create a second script to flip bottom monitors (A 💱 B) on demand.
• Hotkeys: bind layout scripts in Settings → Keyboard → Custom Shortcuts.
• LightDM global hook: add display-setup-script=/path/to/script under [Seat:*] in /etc/lightdm/lightdm.conf for system‑wide layout—great for shared PCs.
• Persist across docking/undocking: use udev rules to run the script whenever the USB DisplayLink device connects.

8. SEO Resources & Further Reading 🌐 

• Synaptics (DisplayLink) official Ubuntu driver downloads
• Ubuntu “Additional Drivers” wiki
• xrandr man page: man xrandr
• NVIDIA X Server Settings documentation
• GitHub: displaylink-rpm & displaylink-debian community installers

🎉 Wrap‑Up

You now have a stable, hands‑free, multi‑monitor workstation on Ubuntu—even with the notoriously finicky combo of DisplayLink and NVIDIA.
Set it once, forget it, and focus on getting real work done. 

Happy hacking—and may your pixels always line up! 🙌

Building a Multi-Environment Kubernetes Cluster for Dev, Staging, and Production

Kubernetes has emerged as the de facto standard for orchestrating containerized applications, allowing teams to achieve consistency, scalability, and reliability across all stages of the software development lifecycle. One of the most common patterns for modern application delivery involves having multiple environments—such as development, staging (or QA), and production—deployed on Kubernetes. Each environment helps ensure quality, maintain isolation, and streamline continuous delivery, all while maintaining a single standardized platform.

In this article, we’ll walk through the key considerations, patterns, and best practices you’ll need to build a multi-environment Kubernetes cluster architecture. Whether you’re starting from zero knowledge or refining an already complex setup, this guide aims to take you from the basics all the way to a high-quality, production-ready environment.

1. Understanding the Multi-Environment Model

When we talk about “multi-environment” setups, we refer to having multiple, logically separate spaces to run your applications. Typically:

• Development (Dev): The environment where developers test new features, experiment, and iterate rapidly. This environment may not have all the production-grade settings but should still reflect a realistic infrastructure so problems can be caught early.
• Staging (QA): A near-production environment used to test release candidates, integration with other services, performance testing, and quality assurance checks. The staging environment should closely mirror production in terms of configuration and scale but might not be as large.
• Production (Prod): The environment serving real users, customers, or critical business functions. It should be highly stable, secure, monitored, and fully supported by operational best practices.

2. Why Use Kubernetes for Multiple Environments?

Consistency and Portability:
Kubernetes enforces a declarative, container-based approach. Once you define how your application runs on Kubernetes, the same definition (with minor modifications) can deploy to Dev, Staging, and Production. This consistency reduces surprises and ensures that what passes tests in Staging will likely behave the same way in Production.

Scalability and Resource Isolation:
With Kubernetes, you can scale each environment independently. Developers might only need a small cluster with minimal resources for Dev, while Production can be tuned to handle thousands of simultaneous users.

Built-in Deployment Strategies:
Kubernetes natively supports advanced deployment methods (e.g., Rolling Updates, Blue-Green, Canary) that can be consistently applied across all environments. This approach further simplifies the process of moving from Dev to Staging to Production without reinventing the wheel each time.

3. Architecture Considerations

Single Cluster vs. Multiple Clusters:
One of the first design choices is whether to run all environments on a single Kubernetes cluster or to use separate clusters. Both approaches have their pros and cons:

• Single Cluster with Namespaces:
  • Pros: Easier management, fewer clusters to maintain, shared control plane, cost-effective.
  • Cons: Less isolation between environments, risk of resource contention, security boundaries primarily rely on namespace policies and network isolation.
• Multiple Clusters per Environment:
  • Pros: Strong isolation, independent scaling and upgrades, reduced blast radius if something breaks in one environment.
  • Cons: More overhead in managing multiple clusters, potentially higher infrastructure costs.

A Common Hybrid Approach:

• Dev & Staging in a Single Cluster with separate namespaces (such as dev and staging) for simplicity and cost savings.
• Production in a Dedicated Cluster for maximum security, scalability, and uptime.

4. Choosing the Infrastructure

Cloud Providers and Managed Kubernetes:
Most large-scale multi-environment setups leverage managed Kubernetes offerings like GKE (Google Kubernetes Engine), EKS (Amazon Elastic Kubernetes Service), or AKS (Azure Kubernetes Service). Managed services reduce operational burden and provide integrated security, scaling, and networking features.

On-Premises Clusters (If Required):
If compliance, data sovereignty, or latency requirements dictate on-premises setups, tools like Rancher, OpenShift, or Kubernetes on bare metal can be used. However, expect more complexity in cluster maintenance and scaling.

5. Configuring Your Tooling

Infrastructure as Code (IaC):
Use tools like Terraform or Pulumi to provision clusters, networks, and load balancers. This ensures that your environments’ infrastructure can be version-controlled, peer-reviewed, and reproducible.

GitOps for Deployment Management:
Adopt GitOps principles with tools like Argo CD or Flux to manage environment configurations declaratively. In a GitOps workflow, changes to Kubernetes manifests for Dev, Staging, or Production are driven by pull requests in source control, offering a strong audit trail and easy rollback capabilities.

6. Namespace Strategy

When using a single cluster for multiple environments, separate them logically using namespaces. For instance:

• dev namespace for development deployments
• staging namespace for QA/staging deployments
• prod namespace (in the production cluster, if separate)

Apply fine-grained Role-Based Access Control (RBAC) to ensure developers can only deploy to dev and staging, while production deployments might require approvals or a CI/CD pipeline with restricted credentials.

7. Security and Access Controls

RBAC and Policies:
Define clear RBAC rules so that developers have appropriate permissions in Dev and Staging but cannot impact Production. Implement Pod Security Policies (or Pod Security Standards in newer Kubernetes versions) and Network Policies to ensure that services and traffic are confined to their respective environments.

Secret Management:
Use external secret management tools like HashiCorp Vault, AWS Secrets Manager, or GCP Secret Manager, and integrate them with Kubernetes Secret objects. Each environment can have its own set of secrets with different access policies.

8. Resource Management and Quotas

Apply ResourceQuotas and LimitRanges to prevent Dev or Staging from hogging cluster resources. Ensure that each environment’s workloads have set CPU and memory requests and limits. This prevents a buggy development service from affecting the entire cluster’s stability.

9. Networking and Routing

Ingress Controllers and DNS:
Set up Ingress Controllers (like NGINX Ingress or an Ingress Controller provided by your cloud provider) to route traffic to the correct namespace based on hostnames or paths. For example:

• app-dev.example.com → routes to the Dev namespace
• app-staging.example.com → routes to the Staging namespace
• app.example.com → routes to the Production cluster

Service Mesh (Optional):
A service mesh like Istio or Linkerd can help manage traffic, add observability, and apply security policies consistently across all environments. It can also facilitate canary deployments and progressive rollouts for Staging and Production.

10. CI/CD Pipelines

Building a Pipeline for Each Environment:
Configure your CI/CD pipeline (e.g., using GitHub Actions, GitLab CI, Jenkins, or CircleCI) so that after code is merged:

• Unit tests and integration tests run for Dev deployments.
• If Dev passes, automatically promote images and manifests to Staging. Perform integration, load, and sanity tests there.
• If Staging passes quality gates, a manual or automated approval step can promote the release to Production.

Immutable Container Images and Versioning:
Tag container images with semantic versions or Git commit SHAs. Pin Deployment manifests to these specific images in each environment, ensuring reproducibility and easier rollbacks.

11. Observability and Monitoring

Centralized Logging and Metrics:
Use tools like Prometheus and Grafana for metrics and the ELK/EFK stack (Elasticsearch, Fluentd, Kibana) or OpenSearch and Loki for logs. With clear dashboards, it’s easier to spot differences in behavior between Dev, Staging, and Production, and to diagnose issues early.

Distributed Tracing:
In complex microservices architectures, distributed tracing (e.g., with Jaeger or OpenTelemetry) helps you identify performance bottlenecks and errors across multiple services. Ensuring similar instrumentation in all environments means you can debug more efficiently.

12. Disaster Recovery and Backups

For Production (and possibly Staging), implement backup and restore strategies for critical data (e.g., persistent volumes, databases). Frequent snapshots and off-site backups ensure you can recover from data loss or cluster disasters.

13. Testing Promotion Flows

Regularly test the entire promotion flow—Dev → Staging → Production—to catch configuration drift or pipeline issues. Run simulations where you roll out a new feature to Dev, verify it, then push it to Staging, run tests, and finally move it to Production. Document these processes and build confidence in your release strategy.

14. Handling Configuration Differences

While you want environments to be as similar as possible, some differences are inevitable (e.g., scaling factors, external service endpoints, database sizes). Utilize Kubernetes’ ConfigMaps, Secrets, and Helm or Kustomize overlays to parameterize these differences cleanly.

For example, maintain a baseline Helm chart for the application and have separate values files for Dev, Staging, and Production. This approach keeps your core logic consistent but allows environment-specific overrides (e.g., replicaCount: 1 for Dev, replicaCount: 3 for Staging, replicaCount: 10 for Production).

15. Security Posture and Compliance

For Production environments, ensure compliance with standards like PCI-DSS, HIPAA, or GDPR if required. This may mean tighter access control, encrypted communication for all services, and stricter network policies. Some compliance requirements may also apply to Staging for realistic testing, while Dev can remain more flexible.

16. Scaling Over Time

Start small. Your initial multi-environment setup may be as simple as:

• A single cluster with two namespaces: Dev and Staging.
• One separate Production cluster.

As your team grows and your workloads become more complex, you can expand to multiple clusters, add more fine-grained namespaces, incorporate a service mesh, adopt advanced deployment strategies, or integrate a more sophisticated GitOps pipeline.

17. Continuous Improvement and Auditing

Once the initial setup is running:

• Continuously audit resource usage, cluster node sizes, and namespace quotas.
• Regularly review RBAC rules and secrets management policies.
• Update cluster components (Kubernetes versions, Ingress Controller versions, etc.) according to a well-defined schedule.

18. Summing It Up

Building a multi-environment Kubernetes cluster strategy is not just about spinning up multiple clusters or namespaces. It’s a thoughtful process that involves setting up the right infrastructure-as-code pipelines, implementing strong security and access controls, integrating observability, ensuring proper promotion flows, and maintaining a robust CI/CD strategy.

By starting from zero—focusing first on understanding the environment model, then moving through architecture choices, tooling, security, and finally advanced techniques—you can build a stable, scalable, and efficient multi-environment Kubernetes ecosystem. Over time, as you refine this setup and incorporate feedback from your dev, ops, and QA teams, you’ll have a world-class platform that can quickly and safely deliver value to users across all stages of development and production.

Introduction
Helm has become the go-to package manager for Kubernetes, simplifying the deployment and management of complex applications by bundling all the required Kubernetes manifests into easily distributable “charts.” Traditionally, Helm charts have been hosted in dedicated Helm repositories or stored as files in version control systems. However, with the advent of Helm 3 and its support for OCI (Open Container Initiative) specifications, you can now store and distribute Helm charts via Docker (OCI) registries—just like container images.

In this post, we’ll walk through the process of preparing your Helm chart, authenticating to a Docker registry, and using the OCI support in Helm 3 to push your chart to a Docker-based registry such as Docker Hub or a private OCI-compatible registry.

Prerequisites

1. Docker Registry Access:
   You’ll need access to a Docker registry (such as Docker Hub, Amazon ECR, or a self-hosted OCI-compatible registry) and proper permissions to push images.
   • For Docker Hub, you need a Docker Hub account.
   • For self-hosted registries, ensure you have a reachable endpoint and credentials.

OCI Support Enabled (If Needed):
For Helm versions prior to 3.8, you might need to explicitly enable the experimental OCI feature:

export HELM_EXPERIMENTAL_OCI=1

From Helm 3.8 onwards, OCI support is stable and enabled by default.

Helm 3.7 or Later:
OCI support in Helm started as an experimental feature but is now stable in Helm 3.7+. Make sure you have a recent version:

helm version

If you’re running an older version, you can download the latest release.

Step-by-Step Guide

Step 1: Prepare Your Helm Chart

If you don’t already have a Helm chart, you can create one using:

helm create mychart

This command generates a starter chart in the mychart directory. Inside, you’ll find a Chart.yaml, values.yaml, templates, and other configuration files. Adjust the chart’s metadata, deployment configurations, and values as needed for your application.

Step 2: Package the Helm Chart

Before pushing to a registry, you need to package your Helm chart into a .tgz archive. The helm package command does this easily:

cd mychart
helm package .

This command creates a file named mychart-<version>.tgz in the current directory. The version is pulled from Chart.yaml.

Step 3: Enable and Use OCI Support (If Required)

If you’re using Helm 3.7 or earlier, you must enable OCI support by setting an environment variable:

export HELM_EXPERIMENTAL_OCI=1

For Helm 3.8 and later, OCI support is automatically enabled, and you can skip this step.

Step 4: Log In to the Docker Registry

To push your Helm chart, you need to be authenticated to the registry. For Docker Hub, you can use:

helm registry login registry-1.docker.io \
  --username <your-username> \
  --password <your-password>

If you’re using another OCI-compatible registry (for example, ghcr.io for GitHub Container Registry or a private registry), adjust the URL accordingly:

helm registry login ghcr.io \
  --username <your-username> \
  --password <your-personal-access-token>

Successful login means Helm (and underlying tooling) have stored your credentials for subsequent operations.

Step 5: Push the Helm Chart to the Registry

With OCI, Helm treats the registry similarly to how you would push images. The syntax involves specifying an oci:// prefix. For example, to push your mychart-<version>.tgz chart to Docker Hub under your account myusername:

helm push mychart-<version>.tgz oci://registry-1.docker.io/myusername/helm-charts

What’s happening here?

• oci:// indicates that you’re using an OCI registry.
• registry-1.docker.io/myusername/helm-charts is the path to the repository within the Docker Hub. You can think of it like myusername/helm-charts in Docker Hub’s naming convention.

If everything is correct, Helm will push the chart and give you a confirmation message. Your chart is now stored in the Docker registry, just like a container image.

Step 6: Verify the Chart in the Registry

After pushing, you can verify that the chart exists in the registry. While Helm doesn’t have a direct “list” command for registries at this point, you can use helm pull to confirm retrieval:

helm pull oci://registry-1.docker.io/myusername/helm-charts/mychart --version <chart-version>

If the pull succeeds, you’ve confirmed that the chart was successfully stored and can be retrieved.

Additional Tips and Best Practices

1. Versioning and Tagging:
   Treat your Helm charts like container images—use semantic versions and consider appending additional tags for clarity. This makes it easier to manage, roll back, and track deployments over time.
2. Automated CI/CD Pipelines:
   Integrate chart packaging and pushing into your CI/CD pipeline. For instance, a GitHub Actions workflow can automatically package and push the chart upon merging to the main branch.
3. Use Private Registries for Proprietary Software:
   If your application and charts are not open-source or public, consider using a private OCI registry. Many cloud providers offer private container registries with native OCI support.
4. Access Control and RBAC:
   Manage access to your Helm charts using the registry’s authentication and authorization mechanisms. This ensures that only trusted team members or CI/CD agents can push or pull charts.