DEV Community: Alessandra Bilardi

The lazy developer's code quality

Alessandra Bilardi — Thu, 30 Apr 2026 09:25:08 +0000

A repo to refresh, several rabbit holes to dive into

A while ago, at PyCon IT, I attended a talk that opened my eyes on pytest:

simpler test management, especially for mocks
parametrizable fixtures instead of the setUp / tearDown ritual
bare assert instead of a thousand self.assertEqual

I'd like my repo python-prototype, born for educational purposes, to also be a bit of a template I can pull off the shelf for the next projects.

So, with the excuse of refreshing the testing system with pytest and the packaging with pyproject, I started thinking about adding more.

I had been using black and pylint for a long time, so my first thought was: ok, let's bring in formatting and linting too. But I asked myself: isn't there something better that maintains style (PEP 8), docstrings (PEP 257) and type hints (PEP 484) automatically ?

And the environment, can it be modernized too ? With what ? Well, just like there are two schools, emacs and vi, there are also two schools, poetry and uv .. without even mentioning all the others.

What I needed was something to cover code quality, formatting, packaging and beyond: fewer tasks left to memory or to reading the holy README, more chances they actually get done.

Since there's no "all-inclusive package", the plan was to test what was maintained and maintainable, and find the one most suited to my needs.

Today's chosen stack

Four tools, not ten:

uv: the env manager. One Rust binary in place of pip, venv, pyenv and pipx. With poetry, the last two aren't covered and need to be installed separately: fewer satellite tools around.
ruff: formatting and linting. Replaces black, isort, flake8 and most of pylint. Another Rust binary.
pyright: the type checker. Skipping mypy, pyrefly and ty. For now.
pre-commit: a git-hook that runs ruff and pytest automatically before every commit. Just .. remember to set it up at the start of the project !

The single criterion that drove all these choices is least total effort. Fewer tools = less config = less maintenance. The lazy developer wants the toolchain to break before the commit, in case some step gets forgotten. But without overdoing it: just enough to produce quality code.

Stories from the field

Pylint and the 4.35/10 grade

The first run of pylint on simple-sample stings: 4.35/10. A high school grade, not a teaching repo's. I sit down to fix my JavaScript hangover: myClass becomes my_class (PEP 8 naming), foo and bar and foobar become get_param_processing, get_boolean, get_reverse_protected_param (names that say what they do). Up to 9.41/10.

But before claiming victory, three warnings need a decision:

W0223: abstract method not implemented in a subclass. Pylint flags it as a bug to fix. In my case it MUST fail: it's part of the educational example. I keep it.
C0301: line too long. I look: it's an HTTP link in a docstring, can't be broken. I ignore it.
C0104: names like "foo" and "bar" are disallowed. I could disable the rule globally, but here I prefer having spent the hour of restructuring: variables and methods should be expressive.

Each of these decisions is a "the tool is right about the code but not about the context". And here is where pylint's limit shows up: it tells you what it found, not whether it really needs fixing. The case-by-case judgement stays with you: it doesn't change anything by itself.

Pylint doesn't understand pytest

I go looking for trouble, and run pylint on the test suite: a new warning shows up, W0621 redefining-outer-name, on the fixtures:

@pytest.fixture
def mci():
    return MyClassInterface()

def test_mci_creation(mci):
    assert isinstance(mci, MyClassInterface)

Pylint says "you're redefining mci from the outer scope". But this pattern is the way fixtures work: it's not redefinition, it's parameter injection. Pylint reads the code as if it were running it, but it doesn't know how pytest runs it.

False positive. The workaround exists:

@pytest.fixture(name="mci")
def mci_fixture():
    return MyClassInterface()

def test_mci_creation(mci):
    assert isinstance(mci, MyClassInterface)

But it's there to silence pylint, not to improve the code. I don't add it. And here I start thinking that pylint is old for pytest, and it's time to switch tool.

Ruff arrives and takes black's place

I try ruff check and ruff format. It covers practically everything black did for formatting, and a good chunk of what pylint did for linting. One binary. Config in pyproject.toml: a single section instead of two. Execution time: milliseconds.

Ruff openly states the trade-off: it's AST-based and works on a single file at a time, it doesn't "read" the class hierarchy across files. So the abstract method not overridden, which I do need to see, doesn't get flagged. Ruff is a fast surface linter, not a deep analyst.

Ok. Ruff takes black's place and covers most of pylint. For what's missing (abstract method, type consistency across files) I need another tool: a type checker.

The type checker tour

Pylint flagged both typing and scoping errors (W0621 is a style check, not a type one). Choosing a type checker, I focus on the typing front: the scoping front stays out of this tour.

I add type hints everywhere, otherwise the type checkers would throw a sea of red (with nothing to check): the signature def get_param_processing(self, param): becomes def get_param_processing(self, param: bool) -> bool:.

Then I run mypy, pyrefly, ty, pyright on the same code to see who flags what.

Tool	Abstract method not implemented	Return None where type hint says bool	Other
mypy	yes	yes	historical, slow
pyrefly	in a different form	yes	lightning fast, young
ty	yes (interface only)	yes	lightning fast, young
pyright	yes	yes	also flags a third error: the method is used in MyClass

Pyright finds more and has a mature ecosystem: Microsoft maintains it actively, and Pylance (the Python extension for VS Code) is built on top of pyright. Pyright wins. Pyrefly and ty are under active development: I'll come back to them later.

The workflow breaking at the first `make patch`

Setup done. Ruff passes clean. Pyright passes clean. Pre-commit stops me if I forget something. I run make patch for the first "real" release .. and:

make[1]: bump-my-version: No such file or directory

The Makefile was calling bump-my-version directly, and the project's dev-deps were in tests/requirements-test.txt, not in pyproject.toml. So whoever cloned the repo had to know to do a pip install -r tests/requirements-test.txt on top of uv sync, and the release workflow assumed the venv was activated. Too much implicit knowledge, too much hassle.

I'm so used to using uv run that I don't run source .venv/bin/activate anymore, so I tripped over something that "the old-fashioned way" would never have happened.

What did it take to truly hand the environment over to uv ? Well, all I needed was to add every dependency in pyproject.toml with:

uv add --dev -r tests/requirements-test.txt

A single command. uv reads the requirements file, writes everything in [dependency-groups].dev of pyproject.toml (the standard introduced by PEP 735 for dev-deps), updates uv.lock, and installs. The tests/requirements-test.txt file becomes redundant: one less file to handle.

And then in the Makefile I added uv run in front of every Python command:

release:
    uv run bump-my-version bump $(PART)
    $(MAKE) changelog
    git tag -f v$$(uv run python -c "from simple_sample import __version__; print(__version__)")
    git push && git push --tags --force

Now make patch works even from a fresh shell, no activation needed. The venv is no longer tribal knowledge, it's implicit in every command.

Seven sections in `pyproject.toml`, one per tool

pyproject.toml was born for packaging, and from there it picked up the config sections of the project's tools: seven in total.

ruff starts from select = ["ALL"]: I enable every available rule and use ignore for the ones I find too much. Philosophy "everything by default, exclude by name": as ruff adds new rules, I get them automatically. And the "ALL" bundle isn't just style + lint: it includes naming (PEP 8), docstring (PEP 257), type annotations (PEP 484, with flake8-annotations), cyclomatic complexity (mccabe), basic security (bandit-base), import order (isort). Ruff isn't "just" a formatter + linter, it's the umbrella under which black + isort + flake8 + parts of pylint, pydocstyle and bandit live.

pyright in typeCheckingMode = "strict": the default basic lets a lot slide, strict requires complete type hints and explicit returns. It's the mode that surfaces those errors the type checker tour had revealed (and that mypy / pyrefly / ty in default config would have missed).

pytest: minimal config, asyncio_mode = "auto" and testpaths = ["tests"]. The rest lives in the tests themselves.

[dependency-groups].dev: the list of dev-deps with version constraints (PEP 735). uv reads this section for uv sync --group dev.

packaging ([build-system], [project], [tool.setuptools]), bumpversion, git-cliff: handle the release pipeline (metadata + runtime dependencies + wheel and sdist build + versioning + CHANGELOG from conventional commits). A different topic from code quality, but necessary for the modernization and automation goal.

pre-commit lives in .pre-commit-config.yaml (outside pyproject.toml): it points to the official astral-sh/ruff-pre-commit repo for the two ruff hooks (check + format) and keeps a local hook running uv run pytest for the tests. So pre-commit also leans on uv to access the project's venv, just like the Makefile targets.

Plus

The lazy developer adds tools when they're really needed, when it's time to handle some other aspect automatically.

Still on the code quality front, what could be added and when ?

vulture and radon: project-level dead code and complexity reports. When a map of the codebase is needed, for instance before a major refactor: ruff sees the single file, vulture and radon see the whole.
bandit (SAST), pip-audit (SCA) and detect-secrets: if the package becomes an API or handles sensitive data, but here a whole new world opens up ..
mypy in strict mode: a second pass on top of pyright. Today I don't have an example that would push me to add it, pyright strict covers well.
pyrefly and ty: worth re-evaluating especially for projects with many files. They're fast but young.
pre-commit.ci: a hook that runs in CI on every PR too. For a personal one-maintainer project it's overhead, for a shared repo it would make sense.

Realtime transcription: choices and stories for PyCon IT

Alessandra Bilardi — Mon, 20 Apr 2026 21:23:48 +0000

Why all this interest in realtime transcription

It all started with the collaboration with PyCon IT. At PyCon IT 2025 they set up live transcription with local Whisper on a Graphics Processing Unit (GPU), based on the repo realtime-transcription-fastrtc. With the YouTube videos used as tests, all good. With the real audio of a conference room, Whisper started hallucinating: a generative model, if you give it a signal it doesn't recognize, doesn't leave a blank, it writes something anyway.

For PyCon IT 2026 a different path was needed, on a non-negotiable anchor: no hallucinations. If the model doesn't hear, ok, skip a word. If it hears badly, ok, transcribe badly. But it must not write sentences I didn't say.

Fixing Whisper's hallucinations directly (Voice Activity Detection, tuning decoding parameters, logprob filters, fine-tuning, ..) would have been a separate effort: I didn't have the time, with everything else to build. A bigger Whisper I haven't tested. Other paid generative Speech To Text (STT) services either: they stay in the same category of a model that produces text token after token, so the structural risk of invention stays. To get out of the category, a managed service based on acoustic decoding was needed. And since it's PyCon, let's also grab the bonus of decoupling the pieces and writing it in a testable way.

A model that gets it wrong but doesn't make it up

Let's start with the engine. Then with what's around it.

STT: who gets it wrong, who makes it up

I didn't run empirical benchmarks on the three. The choice played out on two axes: model structure (generative or not) and delivery (self-hosted or managed). The properties in the table come from product documentation and from direct observation of Whisper at PyCon IT 2025, not from A/B tests.

Criterion	Whisper local	Amazon Transcribe Streaming	Paid generative STT
Architecture	generative (autoregressive)	non-generative (acoustic decoding)	generative
Hallucinations structurally possible	yes	no	yes
Delivery	self-hosted	managed	managed
Setup	GPU + model	AWS credentials	credentials
Network dependency	no	yes	yes
Cost	on-site hardware	$0.024/min	variable
Declared latency	1-15s end of segment	~300ms partial	depends

The most important criterion is architecture. A non-generative model cannot, by construction, add words it didn't hear: at worst it skips or gets it wrong. A generative model can. The other criteria (network, cost, latency) are secondary trade-offs, all acceptable for a conference context: there's internet, a 30-minute talk costs ~$0.72, partial results arrive in ~300ms.

Choice: Amazon Transcribe Streaming. Not because it's "the best" in absolute terms, but because it sits in the category that rules out at the root the problem we're here for. The repo video-to-text I wrote on purpose to test Transcribe as an alternative to Whisper.

New repo or fork of the old one ?

The other big choice: fork of realtime-transcription-fastrtc (the one already used at PyCon IT 2025), or a new repo that takes only the good pieces from the two predecessors (realtime-transcription-fastrtc and video-to-text) ?

Criterion	Fork	New repo
Initial effort	low	medium
Fragile dependencies inherited	FastRTC v0.0.26	none
Architecture	monolithic to dismantle	designed for the use case
Testability	inherits the existing scope	every component in isolation

Choice: new repo. As a lazy developer one would be tempted to fork, but when a dependency is fragile (FastRTC v0.0.26 isn't a stable standard), a fork could cost more than a targeted rewrite.

From realtime-transcription-fastrtc I keep the screen layout (black background, large text) and the auto-scroll logic of the frontend. From video-to-text I take the transcribe_service.py module and the async pattern with asyncio.Queue + asyncio.gather(). The rest gets dropped.

Architecture: monolithic or decoupled ?

As a lazy developer, I don't want to redo everything moving from Proof of Concept (PoC) to Minimum Viable Product (MVP). The two predecessors already have pieces that work (the screen layout of realtime-transcription-fastrtc, the transcribe_service of video-to-text), but they're pieces from different repos, made for different purposes. To recycle them, the modules need clear boundaries.

A decoupled architecture here means having three components as three separate processes that talk to each other over the network:

the audio client, which captures audio from the system device and sends it to the server
the server, which receives audio, manages the stream toward Amazon Transcribe, and publishes the text
the display client, which receives the text from the server and shows it on the dedicated monitor

The alternative architecture is a single process (a single running program) that captures, transcribes, displays.

Criterion	Monolithic	Decoupled
Deploy	a single binary	three components
Distribution across multiple computers	no	yes (native)
Testability	internal dependencies	each component in isolation
Communication overhead	none	network calls

Choice: decoupled. It works both in development with everything on one computer (localhost), and at the conference with three separate computers: audio client in the control room near the mixer, server on any computer connected to the network, and display client on the computer that drives the monitor. The monolithic instead locks everything onto a single computer, and the code couples the components: tests and replacements require more work. With more rooms the bill gets worse: you'd need a full copy of the system per room (audio, server, display for each), whereas the decoupled shares a single server across all rooms, and each room only adds an audio-and-display client on the same computer, or, to avoid running a long cable across the room, a second display client near the monitor.

Audio client: browser or standalone ?

The audio to transcribe has different sources depending on the context: laptop microphone in local tests, Universal Serial Bus (USB) or analog mixer in the room, browser loopback for live apps like StreamYard. Who picks up this flow and sends it to the server ?

Two candidates: the browser app with getUserMedia (realtime-transcription-fastrtc's path), or a standalone Python script launched from the audio computer.

Criterion	In the browser	Standalone Python script
System devices (mixer)	limited	full access
Browser dependency	yes	no
Testability	medium	high

Choice: standalone Python with sounddevice. At a conference, audio doesn't come from the speaker's laptop microphone, but from a room mixer or a dedicated microphone connected via USB. The browser's Web Audio APIs don't expose virtual sinks and USB mixers as separate devices. Instead, a Python script with sounddevice sees all the devices the operating system exposes, loopback and mixer included.

Protocol between audio client and server

realtime-transcription-fastrtc used Web Real-Time Communication (WebRTC); video-to-text instead WebSocket (WS). Which makes sense here ?

Criterion	WebRTC	WS
Bidirectionality	required	not needed
Network setup	Network Address Translation (NAT), Traversal Using Relays around NAT (TURN), Interactive Connectivity Establishment (ICE)	none
Reliability	path-dependent	persistent connection
Complexity	high	low

Choice: WS. The audio client sends, the server receives. Bidirectionality isn't needed, so WebRTC is overkill. Persistence, on the other hand, is: a talk lasts tens of minutes, audio goes in chunks every 100ms, and on the server the same pipe keeps the Amazon Transcribe stream open for the whole session. WS covers both without the WebRTC layers.

Transcript channel between server and display

realtime-transcription-fastrtc used Server-Sent Events (SSE); video-to-text WS. Which here ?

Criterion	SSE	WS
Fits the case	yes	yes
Tech already in use	no	yes (for audio)
Duplicate code	a second handler	same stack

Choice: WS. SSE would technically be enough (unidirectional server -> client, fine for the transcript). But WS is already in the house for the audio channel: keeping a single technology means a single stack of handlers server-side and a single client-side library, instead of two.

Partial results vs final

Amazon Transcribe sends both partials (text that changes until the segment is stable) and finals (stable). To compare the two delivery modes in the field, the display supports both via the ?partial=true|false flag: picked at runtime, not at build.

Criterion	Partial on by default	Partial off by default
Readability on the monitor	low (changing text)	high
Perceived latency	good	medium

Choice: off by default. A dedicated monitor with text that writes, erases and rewrites is unpleasant to look at. Partials can be turned on via ?partial=true on the display if in a specific room the delay of finals ends up bothering.

Language: zero restart between talks

Amazon Transcribe wants the language when opening the stream (language_code="it-IT" or "en-US"). At PyCon, rooms have consecutive talks in different languages: Italian, English. Two paths: language as a global server configuration, or as a parameter per connection of the audio client.

Criterion	Global in the server	Per-room parameter
Language change between talks	server restart	zero restart
Scalability to multiple rooms in parallel	all same language	each room its own

Choice: per-room parameter. With the global version, a restart would be needed at every language change (or a proxy that discriminates per path, complicating things). With the per-room parameter, the server stays up for the whole day, and the audio client reopens at the next talk with the right language (?lang=it-IT or ?lang=en-US). And it also works with multiple rooms in parallel: each room has its own language, independent of the others.

Concretely: every WS connection is an independent handler on FastAPI, and each opens its own Amazon Transcribe stream with its own language. There's no shared state between different streams, so the language of one room cannot affect another.

Display: dynamic app or static HTML ?

In this case, the display is what the audience looks at: a dedicated monitor with text scrolling as it arrives. It must update in real time receiving messages from the server, but does nothing else: no forms, no interaction.

Two paths: a dynamic app (React, Vue or similar, with build and state management), or a static HTML page with a bit of JS that opens a WS and appends text.

Criterion	Dynamic app	Static HTML + JS
Client-side state	possible	only via WS
Deploy	requires build	file served by the server
Reuse from `realtime-transcription-fastrtc`	no	yes (CSS + JS)

Choice: static HTML. No client-side state needed: the browser opens the page, receives text via WS, shows it. No build. And the CSS of realtime-transcription-fastrtc's screen mode gets reused as is.

Choices at a glance

The realtime-transcription choices don't come out of nowhere: some are new decisions for the live use case, others are pieces lifted from the two predecessors. Here they are in a row, with the source of inspiration. For the sequence diagram with WS endpoints and message flow, see the README of the repo.

Choice	Winning option	Criterion	Source
STT	Amazon Transcribe Streaming	no hallucinations	`video-to-text` (transcribe_service)
Repo	new	less tech debt	new
Architecture	decoupled (3 components)	reuse from predecessors, deploy flexibility	new
Audio client	standalone Python	full access to system devices	new
Audio protocol	WS	persistent connection, minimal network setup	new
Transcript channel	WS	single stack server + client	`video-to-text`
Partial vs final	flag `?partial=true\	false`	readability on the monitor
Language	per room	zero restart between talks, scales to more rooms	new
Display	static HTML	no build, reuse of existing work	`realtime-transcription-fastrtc` (CSS + JS `screen` mode)

The stories you only find when you plug things in

The real fun starts when you stop drawing and turn on the machines.

The device number on Fedora

The first time I ran uv run python -m audio_client --list-devices I found myself facing a long list with the same hardware (my headphones in the docking station jack) showing up multiple times, with similar names and different IDs. On Linux several audio layers coexist (ALSA at the kernel, JACK for pro audio, PipeWire as a modern sound server) and sounddevice lists them all: each exposes the same device, each is a candidate on paper.

Backend	Device ID	Outcome
ALSA	1	doesn't work as one might expect
JACK	25	doesn't work as one might expect
PipeWire (system default)	20	works (it's the active routing of the system)

There's no logic that helps you pick a priori: it depends on what the system uses as default routing. On Fedora 41 it's PipeWire, so the "right" ID was 20. I tried all three before figuring out the logic.

Rule of thumb: if the audio doesn't get where it should, try all the candidates before touching the code.

The browser loopback

One of the audio sources to transcribe is StreamYard, which is a browser app: the speaker's audio goes out of the browser to the system's default sink. audio_client with sounddevice can capture from system devices (microphone, USB mixer), but can't read directly from an app's output. A bridge is needed: a virtual sink the browser writes to, and whose monitor audio_client reads from.

On Linux with PipeWire (or PulseAudio) the bridge is module-null-sink. You load a sink called loopback, you move the browser's stream onto it, you point audio_client at the null-sink's monitor. It works on the first try, but there's a side effect: while the browser's stream is on the null-sink, I can't hear it on my headphones anymore. In the room it's not a problem (audio comes from the physical mixer, not from the laptop browser). In development, yes: I can't verify what I'm transcribing.

I tried three paths: two deaf, one hearing clearly.

Approach	audio_client hears	Headphones hear	Notes
`module-null-sink` + move browser	yes	no	base setup, muted on the laptop
`module-combine-sink` with slaves	no	yes	failed
`module-null-sink` + `module-loopback` as a parallel branch	yes	yes (+~50ms)	adopted solution

The path that works is module-loopback as a parallel branch. The null-sink loopback stays source for audio_client; on top you load a module-loopback that reads from the null-sink's monitor and writes to the default sink. Two independent consumers on the same monitor, neither blocks the other.

The ~50ms is module-loopback's buffer. For the transcription nothing changes: the audio_client branch stays instant. The 50ms is only what I hear in headphones compared to what leaves the browser.

Everything is wrapped in two make commands: make loopback_redirect APP=firefox (which also accepts MONITOR=1 for the listening branch to headphones) and make loopback_clean that cleans up.

Practical choice: default MONITOR=0. At the conference audio comes from the mixer, not the laptop, so hearing it locally isn't needed. MONITOR=1 is a development luxury.

How much hardware do you need ?

I haven't benchmarked the system on specific hardware yet, so I'm basing this on typical sizes of similar Python applications. Better to oversize than to pick the bare minimum: on a real deploy you want margin, not to crash on the first spike.

Component	RAM/CPU	Recommended example	Notes
Audio client	~50-100MB	Pi 4 2GB with USB mic	Pi 3 technically enough but tight
Server	~100-200MB base + ~30-50MB per room	EC2 t4g.small (2GB, ARM) or Pi 4 4-8GB	Pi 4 handles 1-2 rooms; EC2 for more
Display client	~200-300MB for Chromium	Pi 4 4GB	Pi 4 2GB technically enough but tight

Three deploy scenarios:

Scenario	Recommended device	When and why
All separate	Pi 4 2GB (audio) + EC2 t4g.small (server) + Pi 4 4GB (display)	Multi-room conference; server in cloud for sharing
All together	A laptop with 8GB, or a Pi 4 8GB with USB mic	Development, local demo
Audio + server together, display separate	Pi 4 8GB (audio+server) + Pi 4 4GB (display)	A single room, zero cloud; the audio Pi also hosts the server

For one room, two Pis are enough. With a Pi 5 (server) you can push to 2-3 rooms; beyond that, EC2 is the way. EC2 or a more powerful laptop are natural upgrades anywhere, if you want more margin.

Anything else to add ?

What's there today is good enough for one room, with any computer connected to the network. But the design holds beyond, when it's worth it.

More rooms, same setup

If many rooms in parallel are needed, the infrastructure can be handled with aws-docker-host, which spins up an Elastic Compute Cloud (EC2) instance with Docker ready to use. The realtime-transcription server already ships with docker compose, and the opening image describes exactly this scenario.

When one EC2 isn't enough: ECS Fargate

If there are many rooms and the load varies, a single static EC2 becomes tight. Fargate (part of Elastic Container Service, ECS) spins up tasks on-demand and shuts them down when needed. But live transcription lives on long-lived WS, and from the AWS documentation there are some points to configure with care (I haven't tested them on the project):

Sticky sessions: a one-hour WS connection must stay on the same Fargate task. The Application Load Balancer (ALB) supports WS, but the session must be routed with affinity. No per-packet round-robin.
Idle timeout: the ALB target group default is 60 seconds of inactivity. A 20-second pause between sentences isn't inactivity (the client sends silence every 100ms), but it's worth raising the timeout to a few minutes for safety.
Graceful shutdown: during a deploy or a scale-in, the task that's closing must let open Transcribe streams finish, not cut off mid-talk. The container must handle SIGTERM and close the WSs gracefully, giving the client time to reconnect to a different task.

Authentication on the WebSockets

Today the WSs are open: anyone who knows /ws/audio/{sala} can inject audio, anyone who knows /ws/transcript/{sala} can listen. For a deploy in a Local Area Network (LAN) or a private cloud on a Virtual Private Network (VPN) it's perfectly fine. On the public internet you need at least:

a token in the path or query (e.g. ?token=...), validated at connect
rate limit per Internet Protocol (IP) on the audio channel
permission separation: whoever can write on room X may not necessarily be allowed to read it

These are the minimum requirements to expose the endpoints on the public internet.

Docker on EC2 with Terraform

Alessandra Bilardi — Fri, 10 Apr 2026 22:25:12 +0000

Why this project

I was preparing a workshop and needed to expose a url with a specific interface, sparing participants from installing docker or anything else on their machines.

I built the workshop locally with docker compose, which is one of the ways to develop and test locally: it works, it's fast, it's reproducible. And then?

Then you need to move everything to the cloud. And as a lazy developer, why not use that same docker compose?

The point isn't running Docker in the cloud - it's everything around it: HTTPS, custom domain, machine access, data backups, and the ability to rebuild or tear it all down with one command.

With IaC you can manage HTTPS, custom domain, backups, access and cleanup smoothly: everything in one place, versioned, reproducible. Without IaC, you start from scratch every time.

The usual options:

Manual EC2 setup: SSH in, install Docker, configure nginx, certbot, and pray. Slow, fragile, and hard to reproduce.
ECS/Fargate: task definition, service discovery, cluster .. for what ? Using Fargate for a single container is like hiring a moving truck to carry your groceries home.
Docker on EC2 with Terraform: one terraform apply to spin up, one bash scripts/destroy.sh to tear down. Backups included.

The third option is what I chose because it has the simplest architecture .. and the most complex part depends on your user data !

The architecture in the image above is generated directly from the Terraform code (spoiler) in the repo, where you can find the README.md and all the details to use it.

But let's take it step by step. The third option can be implemented in 1024 different ways: which IaC tool ? How do you handle HTTPS ? How do you access the machine ? Where do you store backups ? How do you manage DNS ? Which AMI ? It depends. The point is asking the right questions.

As a lazy developer, every choice follows one criterion: less effort, in terms of time, cost, or both. And when less effort isn't enough to decide, the cleanest path is a minimal system: you know what's there, you know what's missing, no surprises.

Why Terraform and not CDK

	Terraform	CDK
Language	HCL: declarative, simple	TypeScript/Python: powerful but verbose for simple infra
State	Local file, zero dependencies	Requires CloudFormation stack, S3 bucket for assets
Bootstrap	`terraform init`	`cdk bootstrap` already creates resources in your AWS account
Learning curve	Low for simple infra	Need to know both CDK and CloudFormation .. and their quirks
Destruction	`terraform destroy`: clean, predictable	`cdk destroy`, which sometimes leaves orphaned resources

For an ephemeral workshop run by one person, Terraform with local state is the minimum effort. CDK makes sense when the infra grows, you need complex logic, or there's a team involved.

The choices and why

Choice	Why (less effort)	The discarded alternative (more effort)
ALB + ACM	Free HTTPS certificate, auto-renewal, no certbot/nginx	Let's Encrypt on EC2: port 80 open, cron for renewal, more moving parts
SSM instead of SSH	No keys, no port 22, audit trail on CloudTrail	SSH key pair, SG rules, bastion if private subnet
S3 for backups	Costs nothing, survives the EC2, simple CLI	EBS snapshot: tied to instance lifecycle, harder to restore
Route 53 hosted zone	DNS validation for ACM, alias record for ALB, all managed by Terraform	External DNS only: manual certificate validation or HTTP challenge
Amazon Linux 2023 minimal	Clean AMI, you install only what you need	AL2023 standard: doesn't have Docker anyway, but has hundreds of extra packages you don't need
`docker compose up --build`	Works with both `build` and `image`	Separate logic for build vs pull: pointless complexity
Local state	The workshop is ephemeral, one operator, no team	Remote state (S3 + DynamoDB): cost and setup for zero benefit
Conditional VPC	Three modes: use an existing VPC, find the default, or create a new one	Always new VPC: waste for a workshop running in the default VPC
Conditional S3 bucket	Pass one and it uses it. Don't, and it creates one named after the domain	Always new bucket: waste for someone running many workshops and just managing backups

What I learned (the hard way)

The right AMI and how much disk

As a lazy developer, instead of reading the documentation, one command to see what's out there:

aws ec2 describe-images \
  --filters "Name=name,Values=al2023-ami-*-x86_64" \
  --owners amazon \
  --query 'reverse(sort_by(Images, &CreationDate))[:10].[Name, BlockDeviceMappings[0].Ebs.VolumeSize]' \
  --output table

Three variants: minimal (2 GB), standard (8 GB), ECS-optimized (30 GB). The ECS one comes with Docker but is meant to run in an ECS cluster, not on a standalone EC2. Standard and minimal don't have Docker: you need to install it either way.

At that point, what does the standard have that minimal doesn't ? SSM agent and a few hundred packages you don't need. The package comparison page confirms it: no Docker, no buildx, nothing that changes the picture.

Minimal is the cleanest choice: install Docker, SSM agent and buildx in the user data, and you know exactly what's on the machine. One thing to watch: the 2 GB disk isn't enough, set volume_size = 20 and move on.

ssm-user is not root

When you connect with aws ssm start-session, you're ssm-user. You don't have access to the Docker socket. Everything needs sudo. Commands sent with aws ssm send-command run as root though, so sudo is built in.

buildx: no buildx, no build

From Docker Compose v2.17+ the --build flag requires buildx >= 0.17.0. The minimal AMI doesn't have it. Without buildx, docker compose up --build fails even if no service uses build: install it in the user data and forget about it.

That damn cache

After a destroy + redeploy, the new Route 53 hosted zone gets different nameservers. You update the NS records on the DNS provider, everything looks fine. But the browser says no.

dig @8.8.8.8 tells you it's all good. But your local resolver disagrees.

What happens: your ISP's resolver has the old SERVFAIL cached, and until it expires, that domain doesn't exist as far as it's concerned.

The fix: temporarily switch your local DNS to Google (8.8.8.8) and wait for your provider's cache to expire: they say 5-10 minutes, but sometimes (way) longer.

Anything else to add ?

When it's not a workshop of a few hours but something that lasts weeks or months, it's worth investing extra effort to make the system hold up over time. But remember, it's always a temporary solution !

More subdomains: more applications on the same ALB, with routing rules, separate target groups, and potentially more containers on the same EC2 or, if needed, dedicated EC2s per service
Tactical scheduling: start/stop the EC2 to save money off-hours, periodic backups with EventBridge + SSM, not just at destroy
CloudWatch alarms: basic monitoring (CPU, disk, health check) with SNS notifications
Auto-recovery: ASG with min=max=1 to replace dying instances (user data restores everything from S3)
Spot instances: for workshops that tolerate interruptions, ~70% cost reduction

DEV Community: Alessandra Bilardi

The lazy developer's code quality

A repo to refresh, several rabbit holes to dive into

Today's chosen stack

Stories from the field

Pylint and the 4.35/10 grade

Pylint doesn't understand pytest

Ruff arrives and takes black's place

The type checker tour

The workflow breaking at the first make patch

Seven sections in pyproject.toml, one per tool

Plus

Realtime transcription: choices and stories for PyCon IT

Why all this interest in realtime transcription

A model that gets it wrong but doesn't make it up

STT: who gets it wrong, who makes it up

New repo or fork of the old one ?

Architecture: monolithic or decoupled ?

Audio client: browser or standalone ?

Protocol between audio client and server

Transcript channel between server and display

Partial results vs final

Language: zero restart between talks

Display: dynamic app or static HTML ?

Choices at a glance

The stories you only find when you plug things in

The device number on Fedora

The browser loopback

How much hardware do you need ?

Anything else to add ?

More rooms, same setup

When one EC2 isn't enough: ECS Fargate

Authentication on the WebSockets

Docker on EC2 with Terraform

Why this project

Why Terraform and not CDK

The choices and why

What I learned (the hard way)

The right AMI and how much disk

ssm-user is not root

buildx: no buildx, no build

That damn cache

Anything else to add ?

The workflow breaking at the first `make patch`

Seven sections in `pyproject.toml`, one per tool