Recently the TSE put on a little theater show: it “opened up the voting machine” so technicians from the Brazilian Computer Society could look at the components. That’s obviously useless. Showing a motherboard, a processor, and some memory chips proves there’s no malware the way looking at a car’s engine proves the driver is sober. Hardware is just the stage; the play happens in the software. And auditing the software is precisely what’s hard, restricted, full of ritual and short windows — which completely defeats the purpose of public transparency. An audit that only a handful of credentialed people can perform, under supervision, for a few days, is not transparency. It’s a performance.

And for the record: I’m not defending the current system, and I have zero expectations for it. As I summed up in this tweet: the voting machine is just a box, an old PC. Even if the software were perfect, it wouldn’t matter — the processes around it stay secret, done behind closed doors. The machine is a smokescreen. With or without an alternative, I don’t care about it.

Many people conclude from this that the answer is digital elections, but with a different system. This article is a computer science exercise: what would a hypothetically perfect system look like? And, more importantly, the final conclusion: why even that perfect system would not be a viable option.

One thing worth emphasizing before we start: the system I’m about to describe would require no secrecy from the government. No secret components, no secret processes, no locked rooms with credentialed people standing guard. Everything — the code, the data, the whole structure — could be 100% open, accessible to anyone, no restrictions whatsoever. And it would still be possible to prove, mathematically, that fraud is impossible. It’s the exact opposite of the current model, where trust is born out of secrecy.

No patience for code and math along the way? Skip straight to the part where I explain why this wouldn’t work. And at the end of the article, three appendices: is the current system auditable?, how to reward voters who verify their vote, and why “zero knowledge” is so hard to swallow.

“The machine is safe because it’s not on the internet”

Sooner or later, every defender of the current system plays this card: the voting machine isn’t connected to the internet, so it can’t be hacked from the outside. Technically true. And completely beside the point.

First, because isolation says nothing about what the software does. An offline machine can flip votes just the same — you simply get no way to watch it happen. And malware doesn’t need a network to get in: it can come from the factory, from an update, from the supply chain, from a technician with physical access. Stuxnet, the most famous worm in history, crossed the air gap into Iran’s centrifuges on a USB stick. An air gap is an obstacle, not proof of honesty. And notice: the machine’s data has to leave it somehow at the end of the day, on physical media carried around or through later transmission. “Not on the internet” is a logistical half-truth.

Second, and more important: that argument exposes the wrong mental model. The current system’s security comes from physical custody — seals, locked rooms, accredited observers, rituals. In other words, once again, from trusting people and processes you cannot see.

In the system I’m about to describe, the machine could be plugged straight into the internet, publishing every vote to the public tree in real time, and fraud would still be impossible. Not because the network is safe, but because nobody needs to trust the machine:

• What it publishes are opaque commitments: even broadcasting everything live, there is no vote to leak in the published data.
• Every commitment carries a mathematical validity proof: the machine cannot mint an invalid vote.
• The tree is public and replicated by independent observers: nothing published can be altered later without breaking the hashes.
• And if the machine flips your vote at the booth, the Benaloh challenge catches it (that’s Building block 4, further down): it cannot know whether you’ll cast or audit.

Being online or not stops being the question. Security doesn’t live in the absence of a network; it lives in public verification. “Trust us, the machine is locked in a room” becomes “don’t trust anything, check the math.” That inversion is the one thing the current model cannot offer.

The tweet that inspired this post

I recently posted this tweet about end-to-end verifiability (E2E-V). The gist of the idea:

1. Every voter gets a paper receipt with a unique identifier — a hash — that identifies neither the person nor the vote.
2. Each precinct’s votes go into a public structure you can only append to, never delete from (append-only): a Merkle tree (the same principle as a blockchain).
3. That tree is published in full. Any citizen downloads and verifies it.
4. Individual verifiability: each voter checks that their hash is there, no middleman.
5. Universal verifiability: anyone recomputes the tree and checks that it produces the announced total.

I made it explicit in the tweet: this is not a solution, it’s a napkin sketch. The concept exists, it’s mathematically solid, and it’s old news to anyone in computer science. But the reaction was interesting.

The voto de cabresto problem

A lot of the comments got stuck on the same point: the voto de cabresto — the “halter vote”. It’s a historical practice in Brazil: the local political boss buys a poor voter’s vote and demands proof they voted “the right way”. Back in the day it was the pre-marked ballot; today it would be a photo of the voting machine’s screen (which is why phones are banned inside the booth).

And that raises an apparent contradiction:

• If the receipt the voter takes home reveals who they voted for, the vote can be coerced or sold.
• If the receipt doesn’t reveal who they voted for, how does the voter check that their vote went to the right candidate?

I recently posted the answer, albeit only in passing: zero-knowledge proofs (ZK). The same principle behind truly anonymous cryptocurrencies like Monero and Zcash.

The flow would go like this: the voter picks the candidate on the screen; the machine generates a secret random number, computes ciphertext = Enc(election_public_key, vote; random), produces a ZK proof that this ciphertext contains a valid vote, and publishes everything to a public Merkle tree. The voter takes home only a serial number. The serial does not contain the vote, but it lets you prove the vote exists in the tree and was not tampered with.

Here’s what this looks like for programmers, step by step, with real values. And at the end I’ll explain why, even working perfectly, this would fix nothing.

Building block 1: hash as commitment

The foundation of everything is the hash function. A function like SHA-256 takes any input and produces 32 seemingly random bytes. Three properties matter here:

• Deterministic: same input, same output. Always.
• One-way: given the hash, there’s no going back to the input.
• Avalanche: flip one bit of the input and the whole hash changes.

import hashlib

def commit(voto, nonce):
    return hashlib.sha256(f"{voto}:{nonce}".encode()).hexdigest()

commit('Candidato A', 987654321) = 337051f1dbc6a8ef412ecc14067c263d6a0dc83dada6939b51d74b6651727b69
commit('Candidato A', 123456789) = 55512bcd60924abf68d162f1a130023635089974db08ea9cff691e1f209898ab
commit('Candidato B', 987654321) = faf54e90eb84ba4c0446701c3779a382e48d02847bd2301f3836f673c54f9693

Look closely. The first and second hashes hide the same vote — what changes is the nonce, a random number that acts as “wrapping”. The first and third share the same nonce, but different votes. The three hashes have no visible resemblance to one another.

This is a commitment: I publish the hash today, and tomorrow I can reveal (vote, nonce) and anyone can check the hash matches. I can’t change my vote after publishing (the binding property), and nobody can figure out the vote before the reveal (the hiding property).

Except there’s a problem for our election: if the voter takes home both the vote and the nonce, they can show both to the coercer, who verifies the hash and confirms the vote. The halter is back. We need something better.

Building block 2: Pedersen commitments — hiding for real

The Pedersen commitment solves this with modular arithmetic. I’ll use toy numbers so you can check the math by hand; real systems use 2048-bit primes or elliptic curves, but the math is identical.

Take a prime p = 23 and two generators g = 4 and h = 8 (both generate a subgroup of order 11 modulo 23 — check it: 4^11 mod 23 = 1 and 8^11 mod 23 = 1). The commitment to a vote v with nonce n is:

C = g^v * h^n  (mod p)

p, q, g, h = 23, 11, 4, 8

def pedersen(v, n):
    return (pow(g, v, p) * pow(h, n, p)) % p

C(voto=1, n=3)  = 1
C(voto=1, n=9)  = 13
C(voto=0, n=3)  = 6

Same vote, different nonces, completely different commitments. Now the part that matters. Pedersen has a property called perfect hiding: for any commitment C, there exists a nonce that opens C as vote 0, and there exists a nonce that opens C as vote 1. With our toy prime we can prove it by brute force:

C = 1  # the commitment from above, C(vote=1, n=3)

for n in range(11):
    if pedersen(0, n) == C:
        print(f"C abre como voto=0 com nonce {n}")
    if pedersen(1, n) == C:
        print(f"C abre como voto=1 com nonce {n}")

C=1 abre como voto=0 com nonce 0
C=1 abre como voto=1 com nonce 3

Read that again, because this is the heart of the article. The commitment C = 1 is consistent with both stories. Anyone who sees only C has no way to know which one is true — not by brute force, not with a quantum computer, because both openings exist mathematically. The value C simply does not contain the vote’s information.

“Hold on,” you say, “so the voter can change their vote afterwards?” No, and that’s the other half of the property: the commitment is computationally binding. Whoever generated the commitment with (vote=1, n=3) can only reveal the other opening (vote=0, n=0) if they can compute a discrete logarithm — that is, find x such that g^x = h mod p. With p = 23 that’s trivial; with 2048 bits, it’s computationally impossible. To sum up:

• Outsiders can’t discover the vote (hiding).
• Whoever committed can’t change the vote afterwards (binding).

And the final detail that kills the halter vote: the machine generates the nonce, not the voter. The voter sees their choice on the screen, the machine makes the commitment internally, discards the nonce, and prints only the C — the serial. The voter leaves the booth with no way to open their own commitment, even if they want to.

(One implementation detail I’ll simplify from here on: Pedersen hides so well that nobody can decrypt it — not even the authorities at tally time. In practice, the machine also publishes an ElGamal ciphertext of the same vote: just as opaque to any outsider, but decryptable by the authorities at the tally, with a ZK proof that both carry the same vote. Our toy Pedersen plays both roles in this article, to keep the math on small numbers.)

Building block 3: the Merkle tree — a ballot box anyone can audit

Where do these commitments live? In a public structure anyone can download and verify: a Merkle tree. If you watched my video on cryptography in practice — certificates, BitTorrent, Git, Bitcoin, you’ve seen this structure in action: it’s the same one that scales BitTorrent, organizes Git commits, and packs the transactions of a Bitcoin block.

The construction is simple: each leaf is the hash of a vote (one voter’s commitment C), and each internal node is the hash of the concatenation of its two children, until a single hash remains at the top: the root.

def H(x):
    return hashlib.sha256(x.encode()).hexdigest()

eleitores = [(1, 3), (0, 7), (1, 2), (1, 10), (0, 5), (1, 1), (0, 8), (1, 4)]
leaves = [H(f"{i}:{pedersen(v, n)}") for i, (v, n) in enumerate(eleitores)]

With the 8 example votes, the leaves look like this (hashes abbreviated):

eleitor 0: voto=1 nonce=3  -> C=1  -> folha=ef134f2a180ba05d...
eleitor 1: voto=0 nonce=7  -> C=12 -> folha=ce356d2f943ea5af...
eleitor 2: voto=1 nonce=2  -> C=3  -> folha=8e0375adfc1f4563...
eleitor 3: voto=1 nonce=10 -> C=12 -> folha=df284a49f837c454...
eleitor 4: voto=0 nonce=5  -> C=16 -> folha=fd6df9e3530cb74f...
eleitor 5: voto=1 nonce=1  -> C=9  -> folha=e0e9d38f9ccb7a41...
eleitor 6: voto=0 nonce=8  -> C=4  -> folha=e719f7fde83fafda...
eleitor 7: voto=1 nonce=4  -> C=8  -> folha=1393ac80e69a8991...

RAIZ PUBLICA: 48826b6481b574e37156f85e34d877105bc55073fb5a5b981239572a8e7c4b61

(The votes and nonces in the table are shown in the clear only so you can check the math; the public tree holds only the leaves — opaque hashes.)

The root is the “summary” of the whole election: 32 bytes representing every vote. If a single bit of a single vote changes, the root changes completely. The root and the entire tree get published. Any citizen, at home, with open-source code, rebuilds the tree and checks whether the published root matches. That’s universal verifiability.

Now the individual part. Suppose you’re voter 4. Your receipt is the serial — the leaf fd6df9e3530cb74f1f0795b751a43454cab281a431d0558b413e33bba83a4100, which is the hash of your commitment C = 16 at position 4 in the tree. To prove it’s in the tree, you don’t need to download and check all 8 votes — you need only log2(8) = 3 hashes, the path of “siblings” up to the root:

def merkle_verify(leaf, proof, root):
    cur = leaf
    for h_, side in proof:
        cur = H(h_ + cur) if side == "esq" else H(cur + h_)
    return cur == root

prova do eleitor 4:
  (dir) e0e9d38f9ccb7a41...  (irmão: folha do eleitor 5)
  (dir) 3149c3bf17d98fbc...  (irmão: nó dos eleitores 6-7)
  (esq) 3b902c849a40619b...  (irmão: nó dos eleitores 0-3)

verificação local: True
tentando folha adulterada: False

You take your serial, concatenate it with the 3 proof hashes in the right order, hash three times, and check whether you land on the public root. If you do, it’s mathematically impossible for your vote not to be in the tree — because producing a fake proof would require finding a SHA-256 collision, and nobody on the planet knows how to do that. If someone swaps your vote afterwards, your proof stops working and you hold evidence of the fraud in your hand. In a real election with 150 million votes, the proof would be about 28 hashes — fits on a paper receipt or a QR code.

Notice what just happened: you proved that a piece of information is in the public tree and that nobody messed with it, carrying home only a 32-byte number that, by itself, says absolutely nothing about the content. That’s what people mean by “zero knowledge” in this context: the verification happens without the knowledge (the vote) ever having to travel.

Building block 4: the Benaloh challenge — checking the machine on the spot

There’s one blind spot left. The machine shows “vote recorded” on the screen and prints your serial C. At home, you confirm that C sits in the tree. All good? Not quite. What if the machine lied and committed a different vote? The screen shows the candidate you picked, but under the hood it computed the commitment for another one. You would never notice, because the commitment is opaque by design. That’s the hiding property working against you.

The classic fix comes from cryptographer Josh Benaloh, and it goes by Benaloh challenge (or cast-or-challenge). The idea: after the machine shows the commitment C on screen, but before you confirm, you get two options:

• Cast: the vote counts, enters the tree, and the nonce is destroyed forever.
• Challenge: you declare that ballot a test vote. The machine must reveal the nonce and the vote it put inside the commitment, and you redo the math on the spot — in an independent app, on your own phone, not on the machine’s software:

# the machine showed on screen: C = 1
# you challenged; the machine reveals: vote=1, nonce=3
pedersen(1, 3) == 1   # True -> the machine committed exactly what you picked

If it matches, the machine was honest on that ballot. The test ballot is spoiled and never enters the tally — the revealed nonce would make it readable — and you vote again, for real this time.

Now suppose a rigged machine that flips a fraction of the votes. You pick vote=1; it internally records vote=0 and shows C = 12 on screen (pedersen(0, 7) = 12). If you cast, the fraud sails through. But if you challenge, the machine is cornered: it has to reveal a (vote, nonce) pair that opens C = 12. The only one it knows is (0, 7) — and revealing that exposes the swap right in front of you: “I voted 1!”. Opening it as vote=1 would require finding a nonce n with pedersen(1, n) = 12, which is the discrete log problem all over again. With our toy prime a brute force search finds one (n = 10 exists), but with 2048-bit primes a cheating machine flat out cannot produce the answer.

And what springs the trap: the machine cannot know in advance whether you’ll cast or challenge. The decision is yours, made after the commitment is already on screen. If a slice of the electorate tests a few ballots before voting for real, a machine that flips votes at scale gets caught with overwhelming probability. Real verifiable voting systems like Helios and ElectionGuard use exactly this mechanism.

And notice this breaks nobody’s secrecy: the revealed nonce belongs to a spoiled ballot that doesn’t count. The vote that counts keeps its nonce destroyed and its commitment impenetrable.

Building block 5: a real zero-knowledge proof — Schnorr

One more piece is missing. What guarantees that each commitment in the tree contains a valid vote — and not, say, vote = 500, which would inflate the result? The machine must prove the commitment opens to a legitimate value without opening the commitment. That’s a zero-knowledge proof in the strict sense.

The canonical example, and one you can demonstrate with small numbers, is the Schnorr protocol: proving you know a secret s such that y = g^s mod p, without revealing s. The intuition before the math: it’s Ali Baba’s cave. The cave has two passages that meet at a locked door. You prove you have the key by walking in one side and coming out whichever side the verifier calls — without ever showing the key. Without the key, you’d only guess the call right by luck, 50% of the time; after 20 rounds, the odds of fooling anyone are below one in a million.

The mathematical version, with our toy numbers (p = 23, g = 4, order q = 11):

segredo = 7
y = pow(g, segredo, p)   # y = 4^7 mod 23 = 8  (public value)

# 1. commitment: the prover picks a random r and sends t
r = 3
t = pow(g, r, p)          # t = 4^3 mod 23 = 18

# 2. challenge: the verifier picks a random c
c = 5

# 3. response: the prover computes z
z = (r + c * segredo) % q  # z = (3 + 5*7) mod 11 = 5

# verification: g^z == t * y^c (mod p)
esq = pow(g, z, p)                 # 4^5 mod 23 = 12
dir = (t * pow(y, c, p)) % p       # 18 * 8^5 mod 23 = 12
print(esq == dir)                  # True

It works because g^z = g^(r + c·s) = g^r · (g^s)^c = t · y^c. The algebra checks out. Now observe what the verifier saw: the numbers t, c, z, and the final check. At no point did the secret s = 7 show up. And an impostor who doesn’t know s can’t answer an arbitrary challenge: if they guess z = 2, the verifier computes g^2 = 16 ≠ 12 and the fraud is exposed.

And why does the verifier learn nothing about s, rather than just “not much”? Because the whole conversation could have been fabricated by someone who doesn’t know the secret, in this inverted order:

# simulator: pick c and z FIRST, then compute the t that closes the equation
c_sim, z_sim = 5, 9
t_sim = (pow(g, z_sim, p) * pow(y, -c_sim % q, p)) % p  # t = 8

# checking the forged transcript:
pow(g, z_sim, p)              # 4^9 mod 23 = 13
(t_sim * pow(y, c_sim, p)) % p  # 8 * 8^5 mod 23 = 13  -> it matches!

The forged transcript (t=8, c=5, z=9) passes verification and is indistinguishable from a real one. If anyone can fabricate a valid conversation without knowing the secret, then the real conversation cannot contain any information about the secret. That’s what “zero knowledge” formally means. (For use outside a lab, the challenge c is derived by hashing the commitment — the Fiat-Shamir transform — and the proof becomes a single, non-interactive object that anyone verifies offline.)

In our hypothetical election, the machine publishes, alongside each vote, a proof of this kind — in practice, an OR-variant (“the vote is 0 or it is 1”, without saying which) — and any auditor verifies that every vote in the tree is valid, without ever seeing a single one.

Building block 6: what stops phantom votes?

One hole is left, and it’s a favorite among digital-election skeptics: what stops the authority from stuffing the tree with invented votes? Every commitment in the Merkle tree carries a ZK proof that it contains a valid vote — but the proof only guarantees the value is 0 or 1. A thousand phantom votes would be a thousand perfectly valid commitments with perfectly correct proofs. The tree is public, anyone can count the leaves… but who says there should be 8 and not 8,000?

The first answer is replication. The tree follows the transparency-log model — the same Certificate Transparency that protects the HTTPS certificates you use all day: one publisher writes, and dozens of independent observers (parties, the bar association, universities, the press, you) copy the tree, sign the root, and cross-check each other. Rewriting history would mean convincing all of them to accept a root different from the one they already signed.

That protects what’s already published. But creating phantom votes? That’s where the most elegant piece of all comes in, from the same David Chaum who invented digital cash and mix-nets: the blind signature (1982).

The flow: you authenticate at the registration desk like today — ID, biometrics. In the booth, the machine computes your commitment (Building block 2), but before publishing it needs a credential from the desk. The machine blinds the commitment with a random factor and sends the desk only the blinded value — and here being online is no problem at all, as we saw in the air-gap section. The desk, which already registered your authentication, signs exactly once, without seeing the content. The machine unblinds the signature and publishes the pair (commitment, signature). In the end, the desk has no idea which commitment it signed — so it cannot link your identity to your vote. With toy RSA, you can watch the magic happen:

# the desk's toy RSA: n=3233, e=17 (public), d=2753 (private)
n, e, d = 3233, 17, 2753
C = 16        # your Pedersen commitment, the same one from Building block 3

# 1. the machine blinds the commitment with a random factor r
r = 7
cego = (C * pow(r, e, n)) % n       # 2341 -> this is all the desk sees

# 2. the desk, which already logged your authentication, signs the BLIND value
ass_cego = pow(cego, d, n) % n      # 216

# 3. the machine removes the blind factor and publishes (C, s) to the tree
s = (ass_cego * pow(r, -1, n)) % n  # 2802

# any auditor checks: s^e mod n == C ?
print(pow(s, e, n))   # 16 -> the commitment, with a valid signature!

Notice: the desk only saw the number 2341, which to them is noise. They signed 216 without knowing they were signing your C = 16. Yet the pair (C, s) passes any auditor’s verification. It’s a regular digital signature — s is exactly C^d mod n — just produced without the signer ever seeing the document. It looks like a magic trick, but it’s plain RSA algebra: blinding multiplies by r^e; signing raises everything to d, and since e·d ≡ 1, what’s left is C^d · r; unblinding divides by r, leaving C^d.

Now assemble the full picture: a leaf only enters the tree carrying two things — the ZK validity proof (Building block 5) and a credential signed by the desk (Building block 6). The desk issues one credential per authentication, and authentication is a public event: there’s a line at the precinct, poll workers, party watchers, the biometric log, the per-precinct attendance count published every election. At the end of the day, the equation anyone can check is:

number of leaves in the tree == number of authenticated voters.

A phantom vote is a leaf without a credential (doesn’t get in) or a credential without a voter (inflates the count and shows). Removing a legitimate vote breaks the receipt’s inclusion proof (Building block 3). Altering a published vote breaks the hashes on the observers’ copies. Stealing credentials would mean fooling the biometrics in front of watchers. Every fraud path hits a different wall — and every wall is checkable by anyone, from home.

The weakest link: who proves you are you?

Everything before this section is math. But there’s one door no math can lock: authentication. No algorithm proves the human standing in front of you is who they claim to be. That is, honestly, the weakest link in the entire system — and it’s worth facing head-on.

And here Brazil simplifies the problem, because it already paid the expensive part: the voter biometric registry exists and covers over 80% of the electorate — more than 124 million people, per the electoral court. National deduplication already ran: one finger exists only once in the roll, no matter how many forged documents back it up. And fingerprints already release the vote at the precinct — in 2026, in every precinct in the country. For this article’s hypothetical system, biometric authentication is free: reuse what’s already standing.

Of course, that registry existing is itself the privacy bet: biometrics are irrevocable data — you can change a password, not your fingerprints. Aadhaar, India’s biometric registry, had incidents exposing data on over a billion people; the OPM, the US government’s HR office, lost 5.6 million fingerprints in a single 2015 breach. A national biometric database is a single point of catastrophic, permanent failure — and Brazil already made that bet. The hypothetical system doesn’t make it worse; it just inherits it.

For anyone outside the biometric registry, the precinct falls back to the photo ID — and cards get forged. They probably get forged today. But notice what the architecture does to that problem: one forged authentication mints one credential, which yields one leaf in the tree. To fraud at scale, the criminal needs flesh-and-blood people showing up in person, in front of poll workers and watchers, once per fake vote. That’s retail fraud: expensive, visible, slow. A thousand fake votes require a thousand bodies — and then it’s not silent digital fraud anymore, it’s chartered-bus logistics everyone sees rolling by. The system doesn’t prevent forgery; it caps the damage per forgery at exactly one vote and pushes the cost into the physical world.

And anomalies surface: the equation from Building block 6 — leaves == authentications — can be checked precinct by precinct. A precinct with 400 registered voters and 420 authentications raises eyebrows. Regional turnout above 100% raises eyebrows. And if paranoia runs high, the desk’s signing key can be fragmented like the election key, requiring a quorum to issue credentials.

The honest summary: the link stays physical and human — a human proving, once, in public, that they’re on the roll — and no system, however perfect, eliminates it. The best possible design does two things with it: shrinks the trust surface down to that single event and makes its failures visible instead of silent. With biometrics valid at every precinct in 2026, identity forgery becomes the most expensive, least scalable path of all — which is exactly where a well-designed system wants it. There’s no free lunch, and pretending there is one is the kind of pitch this whole article refuses to make.

Putting it all together: the full protocol

The hypothetically perfect election would go like this:

1. Setup. A group of independent authorities (the electoral court, the bar association, parties, civil society) jointly generates the election’s public key. The corresponding private key stays fragmented: no single authority can decrypt anything; only a majority acting together can.
2. Authentication. The voter identifies at the registration desk — ID, biometrics, like today — and the desk logs the authentication. This authorizes the issuance of one credential: the blind signature on a commitment, without the desk seeing the content. No link between identity and vote.
3. Voting. The voter picks the candidate on the screen. The machine generates a random nonce, computes the Pedersen commitment and the ElGamal ciphertext of the same vote (the commitment becomes the receipt’s serial; the ciphertext is what gets tallied), produces the ZK validity proof, and shows the commitment on screen. The voter then decides: cast, and the nonce is destroyed — or challenge, and the machine reveals the nonce for an on-the-spot check, the ballot is spoiled, and they vote again. Once cast, the machine blinds the commitment, the desk signs it sight unseen, and the machine unblinds the signature.
4. Publication. The commitment goes into a public Merkle tree, together with the ZK proof and the credential — replicated and signed by multiple independent observers. No credential, no entry.
5. Receipt. The voter takes home a slip of paper with the serial. They cannot prove to anyone who they voted for — even if they want to, because they don’t have the nonce.
6. Individual verification. At home, the voter downloads the tree (or uses any independent website) and checks their serial is there, with the inclusion proof. If it isn’t, they hold material proof of fraud.
7. Universal verification. Any citizen, university, or party rebuilds the entire tree, checks the root, validates every ZK proof and credential, and confirms the leaf count matches the published per-precinct authentication totals.
8. Tallying. In the end, the encrypted votes go through a mix-net (they get re-shuffled and re-encrypted, severing the link to their original positions) and the authorities decrypt jointly, proving each step. The total matches the public root, or the fraud is evident.

Notice what changed relative to the current system: you no longer need to trust the electoral court, the voting machine, or any auditor. Every property is individually verifiable by anyone with a computer. It’s the same principle that lets Bitcoin work without a central bank: don’t trust, verify.

Before anyone gets too excited: this is a simplification. A real system still has to solve anonymous credentials more robust than our toy blind signature, tree availability, and a pile of operational details. The point here is not the complete design; it’s the core mechanism.

Why this would never work

Now for the part almost nobody proposing these systems wants to hear.

Scroll back to the beginning of this article and notice what I had to explain to get here: hash functions, commitments, modular arithmetic, discrete logarithms, Merkle trees, the Benaloh challenge, blind signatures, zero-knowledge proofs, simulators. With code, with numbers, with step-by-step examples. And even so, I’d bet a good share of readers — programmers included — made it here without full certainty that they truly understand why the scheme is secure.

And that’s not for lack of intelligence. It’s because trusting this system requires understanding math that the vast majority of the population will never understand. The only human being who can be 100% certain this system is correct is the one who can verify the mathematical proofs on their own. Everyone else — 99.9% of the population — wouldn’t be verifying anything. They’d be believing the mathematician who says it works.

And here we hit the fatal contradiction: if an electoral system requires the ordinary citizen to blindly believe a specialist they can’t audit, it is exactly as opaque as the TSE’s current system. The opacity just moved address: instead of trusting the court bureaucrat, you trust the cryptographer. For dona Maria, who sells pastel at the street market, it’s all the same — both are “a bunch of mumbo-jumbo I don’t understand”. And a system the population cannot understand is a system whose legitimacy it will never accept. Today’s skeptic saying “I don’t trust the voting machine” would become tomorrow’s skeptic saying “I don’t trust this algebra”.

An election is not only an engineering problem; it’s a social trust problem. The gold standard of transparency is the system anyone can watch with their own eyes: paper ballot, glass ballot box, public counting at the precinct, the tally posted on the door. Anyone understands paper being counted in public. Nobody has to believe anybody.

That’s why countries far richer and more technological than Brazil — Germany, the Netherlands, France, most of the US — stick with paper or demand an auditable paper trail. That’s not backwardness. It’s the recognition that verifiability only specialists understand is not public verifiability.

Sidebar: what cryptocurrencies prove every day

Before wrapping up, a detour to answer the question that always comes up: “but does this actually work, or is it napkin theory?” It works. And the proof has been running for almost two decades, moving billions of dollars, under constant attack: blockchains.

First, clearing up a misunderstanding: blockchain is not synonymous with cryptocurrency. As the name says, it’s just a chain of blocks. Each block carries a Merkle tree of records and the previous block’s hash. In Bitcoin, the block header holds the transaction tree’s root, the previous block’s hash, a timestamp, and a nonce — here, a mining counter — that miners vary until the hash of the entire block falls below the difficulty target: the famous proof of work. It’s Building block 3 of this article, extended through time: not one tree, but a chain of trees, each sealing the one before.

The practical result is the guarantee that matters here: tamper with one transaction in an old block and the tree’s root changes, the block’s hash changes, the link to the next block breaks, and to hide that you’d need to redo the proof of work of every block up to today — while thousands of honest nodes keep extending the true chain. Once everything is signed and sealed by hash, rewriting the past is computationally impossible. That’s exactly why Bitcoin can be 100% public: the exposure itself is the protection. Everyone has a copy of everything, so nobody rewrites history.

But public does not mean anonymous. That’s the part most people get wrong. In Bitcoin, every transaction stays visible forever: which addresses fed it, which received, how much moved. Addresses are pseudonyms — pen names, not anonymity. And there’s an entire chain-analysis industry (Chainalysis, Elliptic, TRM) making a living gluing identities to those pen names:

• Common-input heuristic: if a transaction spends coins from several addresses, they almost certainly belong to the same wallet. Group them into a cluster.
• Change detection: the output that returns to a fresh address usually belongs to the payer.
• Bridge to the real world: when a cluster’s address touches a KYC exchange, a name and a tax ID attach to the whole cluster — and to its complete history, retroactively.

That’s how the FBI recovered part of the Colonial Pipeline ransom, that’s how the Silk Road coins were traced years later, and that’s how the ~1,128 BTC stolen from ColdCards are still sitting in known addresses half the world is watching — I detailed it in the article about Coinkite’s RNG. If the thief moves a single satoshi to a KYC exchange, they identify themselves. The chain guarantees integrity, not secrecy.

For real anonymity, the chain alone doesn’t cut it: you need zero-knowledge proofs. Monero, for instance, combines three techniques:

1. Ring signatures: each spend is signed on behalf of a group of possible keys. The signature proves one of them authorized it, without revealing which.
2. Stealth addresses: the recipient’s address never appears on the chain; each payment creates a disposable address derived from a shared secret.
3. RingCT (confidential transactions): amounts stay hidden inside Pedersen commitments — yes, the exact same Building block 2 from this article — and a ZK range proof guarantees nobody minted coins out of thin air, without revealing any amount.

Zcash follows the same philosophy with zk-SNARKs: you prove “I own a valid, unspent note” without revealing which note. The network verifies the proof, accepts the transaction, and learns neither sender, recipient, nor value.

And here the circle closes. Look at what this article’s electoral scheme uses: a public, immutable structure anyone can verify (the Merkle tree, the blockchain’s simpler cousin), Pedersen commitments to hide content (the same primitive as Monero), and ZK proofs to guarantee validity without revelation (the same family as Monero and Zcash). None of this is lab conjecture: these are production systems, audited, attacked daily, protecting real money. An election is, if anything, a simpler problem — short window, a single publisher, offline verification.

That’s why I said at the beginning that the idea is mathematically solid: it invents nothing, it just composes pieces that already proved they can survive the real world. We know an end-to-end verifiable digital election could be built, because every one of its components is already built and running. Which brings us back to the problem that isn’t technical.

Conclusion

Let me make it clear once more, as I did in the tweets: this is not a proposal, it’s an exercise. I don’t know the solution to Brazil’s electoral trust problem. If I did, I’d be publishing a paper, not a blog post.

But the exercise is worth it for two reasons. First, because it shows the technology for individual and universal verifiability exists — anyone who says “digital elections are inherently unauditable” is wrong. Second, because it shows the real limit: the frontier isn’t technical, it’s epistemological. A perfect system nobody understands fails at the same point as an imperfect system nobody can audit.

If you understood every line of this article, congratulations: you’re part of a minority far too small to carry a democracy on its back.

Appendix 1: so is the current system auditable?

A fair question hangs in the air: so the current system has no auditing at all? It does, and it’s worth being honest about that. What doesn’t exist is a specific kind of audit: one that doesn’t depend on software. Let’s take it piece by piece.

The current arsenal, summarized and sourced:

• Source code inspection. Parties, the bar association, the federal audit court, the Federal Police, the prosecutor’s office, and universities can examine the systems’ code at the electoral court’s headquarters, months before the election — the so-called transparency cycle.
• Public Security Test (TPS). Outside researchers genuinely try to attack the system. And it works: in 2012, professor Diego Aranha’s team unscrambled the RDV and showed it was possible to learn who each voter had voted for; in 2017, they managed to tamper with the voting software before installation (the story is in Revista Pesquisa FAPESP and in this Lupa summary). The flaws found were fixed afterwards.
• Zero report, BU, and the Integrity Test. Before voting starts, the machine prints a zeroed-out report. At the end of the day, it prints the Boletim de Urna, posted at the precinct and published digitally with a QR code — anyone can download the BUs and add them up independently. And a random sample of machines is diverted to a filmed parallel vote, comparing the paper record against the digital one.
• RDV — the “digital recount”. The machine records each individual vote in a shuffled, anonymized file, published afterwards (definition in TSE Resolution 23.673/2021). Parties and authorized entities can re-sum the votes and cross-check against the BUs and the official tally — the official mechanism presented as the substitute for a paper recount (the electoral court’s explanation).
• External audits. In 2022, the federal audit court (TCU) cross-checked 9 million records from 4,577 precincts against the tallying database and found zero discrepancies — probability of fraud “approaching 0%” (CNN Brasil). The Carter Center observed the 2022 elections, registered no evidence of fraud, and acknowledged the audits’ expansion (mission statement).

Now the “but” this whole article builds toward: every layer on that list depends on software or on a ceremony run by the electoral court itself. The BU × RDV comparison proves internal consistency — that the published numbers match the recorded numbers. It does not prove the recorded numbers reflect what voters pressed on the screen, because a tampered machine would produce a tampered BU and RDV in perfect mutual agreement. As Aranha himself puts it: every audit available today depends on the software; if the program is tampered with, every check falls together (Folha de S.Paulo). And the Integrity Test, which covers a small sample of machines, is a poor cousin of the Benaloh challenge from Building block 4: instead of each voter auditing their own ballot on the spot, the auditing is done by a sample drawn and conducted by the system itself.

There’s also the legal chapter: the attempt to create a voter-verifiable paper record, the “printed vote,” was ruled unconstitutional by the Supreme Court in ADI 4543 over ballot-secrecy risks, and the attempt to revive it was struck down again in 2020 (Conjur). The irony is that this article’s scheme resolves exactly the conflict that killed the printed vote: a verifiable receipt without breaking secrecy, via commitments and ZK proofs. The math unlocks what paper couldn’t. Everything else stays locked, as the previous sections explain.

So the honest verdict: the Brazilian system is auditable in real digital and procedural ways, and no fraud altering an outcome has ever been proven in nearly 30 years of electronic voting. But there is no software-independent recount, because there is no voter-verified physical record. In the language of election-security research, a true risk-limiting audit is not possible. Trust stays deposited in the software, the pre-election inspections, and the custody of digital records — exactly what this article’s hypothetical system tries to eliminate.

Appendix 2: skin in the game — rewarding those who verify

One question hangs in the air after assembling the whole scheme: cryptocurrencies work because someone has something to lose. In Bitcoin, the miner burns real energy; in proof-of-stake, the validator deposits capital that gets confiscated if they cheat. And the voter? Voting costs nothing, and checking the receipt at home is work you do for free. The entire system depends on people verifying — and nobody has an incentive to verify. Can you put skin in the game on the voter?

The first idea that comes to mind is a deposit: vote, deposit some money, get it back later through the income tax system. As mechanism design, it has logic — it prices fake identities: a million phantom votes would cost a hundred million reais. In practice, it dies in three places. It’s a disguised poll tax, exclusionary and unconstitutional — the refund fixes the accounting, not the cash flow of someone who doesn’t have the money to front. The “income tax” channel doesn’t reach most poor Brazilians, who don’t even file — so it excludes exactly who the system most needs to include. And it would build, at the tax authority, a database linking identity, bank account, and electoral participation — a surveillance regression bigger than the problem it solves. All that before the plutocratic detail: security priced in money is security buyable by those who have money. Elections are designed to be wealth-blind — one vote per person. Putting a price on the security layer invites the rich to be more equal than the others.

The version that survives this scrutiny flips the sign: instead of charging to vote, reward those who verify. The scheme’s real soft spot is the individual verification rate — if nobody checks their serial at home, the inclusion proof from Building block 3 becomes decoration. So: every verified receipt enters a public, auditable lottery, with the tree’s own root serving as the randomness source (one more use for it). Checked your vote in the tree? You’re in the drawing for a prize. The incentive points exactly at the behavior the system needs — millions of eyes checking the tree — without excluding anyone, charging anything, or building a new database, because the lottery runs on the anonymous serial, not on identity.

It’s Bitcoin’s logic on the right side: there, the block reward pays thousands of machines to keep the ledger honest; here, the prize would pay millions of voters to keep the election honest. It’s almost a proof of verification: the block reward pays for the hashing work that keeps Bitcoin going, and the prize would pay for the checking work that would keep the election going. It’s not a proposal — like nothing in this article — but as an incentive-design exercise, it’s the version I’d put on paper.

Appendix 3: why “zero knowledge” is so hard to swallow

If you made it here feeling like you understood each piece individually but wouldn’t swear you understood the whole thing, relax: you’re in excellent company. When Goldwasser, Micali, and Rackoff formalized zero-knowledge proofs in the 1980s, the idea sounded paradoxical even to career cryptographers. Every proof we’d ever known worked by showing something. How can a proof transfer conviction while transferring no information at all?

The math from Building blocks 2 through 5 is the complete answer, but intuition lags behind. So here are two classic analogies involving no equations at all — each one lights up half of the concept.

Where’s Waldo? I claim I found Waldo on the page, and I want to prove it without revealing where he is — otherwise you win the game for free. The solution: I take a huge sheet of cardboard, much bigger than the book, cut a small hole in the middle, and place it over the page so only Waldo shows through. You see Waldo. But since the cardboard covers everything around him, you have no idea which corner of the page he’s in. I proved I know the location; you learned zero about it. And notice what holds the proof up: if I didn’t know where he was, I couldn’t have positioned the cardboard — the odds of landing the hole on Waldo by luck are tiny. It’s Ali Baba’s cave all over again, this time with cardboard.

The color-blind friend’s two balls. Your friend is red-green color-blind. You have two balls identical in size, weight, and texture — one red, one green — and you claim: “these balls are different colors.” To him, they’re indistinguishable. How do you prove it without revealing which is which? He shows you the balls, one in each hand. He puts his hands behind his back and decides, on his own, whether to swap them or not. He shows them again and asks: “did I swap?” You, who see the colors, answer correctly every time. He, who doesn’t, couldn’t do better than 50%. After 20 correct answers in a row, he’s convinced the balls differ — the odds of you bluffing 20 rounds are one in a million. And what did he learn about which ball is red? Nothing. Every answer you gave (“swapped”, “didn’t swap”) was something he already knew — after all, he was the one who decided whether to swap. The round’s information was already his; the only new thing is the conviction that you can see the difference.

The formal version of that intuition is the simulator from Building block 5: if anyone, knowing no secret at all, can fabricate a “recording” of a proof session indistinguishable from a real one, then the real session cannot carry any information about the secret. The convincing power comes from the order of operations — commitment first, challenge after. The zero knowledge comes from the recording, on its own, being forgeable. Both things are true at the same time, for different reasons. That’s why the concept feels slippery: you’re holding two facts that seem to contradict each other until you notice each one rests on something different.

And if the concept still feels slippery after all of this, good: you’ve just experienced the article’s central argument firsthand.

I’ll do only this one article about it and I don’t intend to cover more than the tip of the iceberg. The idea is to serve whoever is coming from other editors like Sublime Text or VS Code and can’t even start navigating or even quit Vim lol 🤣.

Initial Commands

As I said in the previous post about LazyVim, I’ll assume you already understand at least how to install support for your language with LazyExtras and already learned to version things using Mise.

Without even getting into LazyVim, the first thing to know is that it installs all the relevant configurations in the ~/.config/nvim directory. Normally you don’t need to touch anything there. Leave files like lazyvim.json alone. Notice that it does the same thing as any NPM out there: there’s a lazy-lock.json file that declares the version/commit of each installed plugin. LazyVim does something similar to an npm install. Just a curiosity so you know how it organizes itself.

If you need to customize something, it’s usually going to be in the ~/.config/nvim/lua/config directory. That’s where I added Mise support, for example:

~/.config/nvim
❯ cat lua/config/mise.lua
-- Prepend mise shims to PATH
vim.env.PATH = vim.env.HOME .. "/.local/share/mise/shims:" .. vim.env.PATH

They’ll always be scripts written in Lua. And you don’t even need to know Lua deeply. At a glance it’s a very simple language, not very different from Python or Javascript and any programmer should be able to read any snippet without any problem. Besides, in most cases you’ll be copying configurations you got from the documentation, wiki or ChatGPT itself, so you just need to know that things go in this location.

Understand that NeoVim has the concept of the “Leader” key, a key that precedes hotkeys for other commands (there’s also localleader which is backslash \). This is configurable but in LazyVim the Leader is the “Space” key. In a lot of documentation we’ll see people saying “press Leader-w”, which means Space+w and now you know what that means.

To open a file there are at least 3 different ways, 2 of them shown in the image above:

Space+E opens NeoTree, which is that sidebar on the left that looks like Windows Explorer. You can navigate with the keyboard or even with the mouse. Find your file and press “Enter” to open it, then “Space+E” again to hide the sidebar. If you want to know how to create a new file, a new subdirectory, rename things and so on, type ? (question mark) to see this help:

The third way is manually with the :e command followed by the file name in the local directory. It has autocomplete too, this is the fastest way, if you know what you’re looking for.

Whenever you want to cancel anything or close “floating windows” (pop-ups, dialog boxes). Just press “Esc”. Esc is fundamental in NeoVim.

Once a file is open, it sits in the Buffer. Think of Buffer as “Open Tabs” in your VS Code. To navigate through Buffers (like alt+tab between your already-opened files) it’s simple:

• ]+b for next “tab” (next Buffer)
• [+b previous Buffer
• Space+bd to “close the tab” (close the Buffer)
• Space+bo to stay where you are and close the other buffers

Open as many files as you want. If one of them is one of those huge logs you opened by accident, Space+bd to close it and done.

Speaking of closing, how do you exit NeoVim? There are several ways:

• Space+q
• :q
• :q!

The difference: the first is the custom way in LazyVim. The second is the standard way using the “commands” feature that always starts with “colon”. And the third is if you modified something in the file but want to cancel, exit without saving anything, hence the exclamation mark.

Normally I use :wq which means “write” and “quit”. So it first saves the changes to the file and then quits the program. It’s useful when I’m just quickly editing a config file.

Basic Navigation

Now I have a file open. How do I navigate through it? First, how do I go to the end of the file and then back to the beginning? This is something I use a lot, just type Shift+g to go to the end of the file and then gg to go back to the beginning. Simple as that.

Now let’s learn several commands at once:

• Type v. This starts the “visual mode” which, in practice, means starting to select from wherever your cursor is.
• Type j. Which is the equivalent of “arrow down” to go to the line below. You’ve probably heard that in Vim you navigate with “hjkl” which are, respectively, left, down, up, right.
• Type x. Which is the equivalent of “cut” and putting the content in the clipboard. Having done that, typing p gives you “paste”.
• Type u. Which is the most-used command: Undo or undoing the last modification.

All of this works in what’s called “command mode”, which is the default mode Vim opens every file in. In this mode you can’t type any text. As you can see, each letter by itself is a command, like “x” for cut or “p” for paste.

To type, you first need to press i (just the lowercase “i” letter), which then switches from command mode to “edit mode”. Now just type your text normally, like in any editor. When you want some command, just press ESC to go back to command mode. We’ll be doing this all the time, which is why a lot of people remap the “caps lock” key on the keyboard to be ESC so it’s easy to just tap with your left pinky.

Combining Commands

Still in command mode, how do we navigate through the file more easily?

Beyond the “hjkl” keys, we can navigate more easily using b for “previous word” or w for next word:

Command mode lets you combine commands, so we can do:

• dw to delete the next word
• db to delete the previous word
• d4w to delete the next 4 words
• d4j to delete the next 4 lines down

Primeagen’s tutorial has several exercises for this kind of navigation, I recommend practicing. In VS Code everyone is used to first grabbing the mouse, marking the block they want to delete visually, then pressing delete or backspace. In Vim, we look at where the cursor is, press ESC to be in command mode, and type the operation and the location. Test all the combinations you can imagine.

This is the paradigm shift that bothers the lazy. But once you’ve learned this, you’ll find it annoying to use an editor that forces you to use the mouse for basic things.

Now it gets more interesting: what if instead of deleting a word, I want to replace the word where my cursor is with another word?

In a normal editor, you’d mark it with the mouse (or use some combination like “ctrl+shift+arrow”), and type over it or delete the word.

In LazyVim there are plugins configured for more interesting things. In the video above see how I’m replacing words “in-place”. You do this with the ciw command.

• ciw deletes the entire word under the cursor and opens edit mode for you to type the replacement
• ce deletes from the cursor to the end of the word (preserves the beginning of the word) and also opens for you to type in its place
• Shift-c (capital C) deletes everything from your cursor to the end of the entire line and opens for you to type.

But that still doesn’t look thaaaat cool. What if you want to change only the first letter of several lines at the same time, for example, in the text of the video above, I want to change only the hyphen ("-") of each tag line?

I said before that pressing v in command mode starts visual mode and you can select from there. But there’s Ctrl+v which opens vertical block selection mode.

In this mode we use the “hjkl” keys normally, like j to go down, but instead of marking the next entire line, it marks only the character right below your cursor. Now I can delete with d and type Shift-i (capital “I”) to enter edit mode at the beginning of the block and replace with whatever I want.

LazyVim has plugins for comments, but this is another alternative if you want to add “//” or “#” at the beginning of several lines to comment out, for example. In this case, read about the ts-comments plugin for better options for commenting. To start a new comment block, type gco to add a comment below.

“Block mode” as I showed above, is one of the things I use the most in code.

But only that is very little. What if you want to replace ALL IDENTICAL WORDS in the text at once. In the example video above, I want to replace “domínio” with “DOMAIN” and “Cloudflare” with “AWS Amazon”, how do I do that? This is “Search and Replace” that exists in every editor and in Vim it’s very easy:

We type :%s/domínio/DOMAIN/.

If you’re a programmer you’ve probably seen this syntax before. It’s the REGEX MATCH syntax. Yes, you have to know Regex (and no, it’s not PCRE nor Unicode, it’s NeoVim’s own Regex dialect, but it’s similar).

As I said before, “colon” opens the command-typing box, "%s" starts “search with regex” and between the slashes “//” first goes what you’re looking for and then what you want to replace it with.

But that’s the way in pure NeoVim; in LazyVim, there’s the grug-far plugin and you activate it with the SPACE+sr command:

Now yes, more like VS Code, right? Use whichever you find easier.

Conclusion

As I said, this is only the tip of the tip of the iceberg, the bare minimum of the bare minimum to at least start editing simple config files without opening Nano or VS Code just for that.

Read the LazyVim documentation. Check out the keymaps to discover other commands. Pay attention to every letter you press in command mode, LazyVim shows the available options. For example, let’s say I pressed g (goto), it will show a help in the bottom-right corner:

This way you can always discover new commands or remember commands you rarely use. That’s why I recommend LazyVim, which comes well configured to help you. The plugin that provides this feature is which-key, in case you want the same thing in a NeoVim you configured from scratch.

There are several Cheatsheets out there with tables of important command combinations. Worth exploring.

And there’s more: LazyVim comes with dozens of plugins for formatting, linting, integrated LSP, integrated GIT, and much more. There’s no way I can document each one here. Each of them has its own documentation on the LazyVim.org plugins page.

Again, don’t forget to call :LazyExtras and install the optional plugins for your languages.

The questions I get the most, literally every single day, come in this format: “Akita, should I go to college?”, “Akita, what do you think I should study?” and variations of that.

Dude, I don’t know you, I will never know nor will I ever be interested in knowing who you are, what you aim for, your aspirations, ambitions, tastes, preferences. Nothing. Neither me nor ANYONE ELSE. Only you know what’s best for you. If you don’t know, go find out. That’s what LIVING means.

What you won’t admit is that you want someone you consider more important or relevant to approve your choice and tell you that you got it right.

Never expect that from me, I will never validate you.

I will always say: FIGURE IT OUT. That’s how I became who I am. I never followed anyone, I never asked anyone what I should do. I just went there and did it. Fell on my face, got up, tried again. That’s life.

Let me show you what actually BOTHERS me:

Let’s check the manual?

DHH took the trouble to write a manual. It has a section called “Security”. A quick Google search would have found it. Or this other gem:

How do you want to become a “DEVOPS” (who has to know EVERYTHING about Linux) starting like this? Already off to a bad start. Park your butt in the chair, roll up your sleeves, and test them one by one, and learn.

Linux for Beginners?

That said, watch my video. But since I’ve been talking a lot about Omarchy already, I’ll say that yes, this is what I use in my day to day and it’s the only one I’ll recommend for the near future (I may change my mind later). Having used distros ever since Linux was invented in the early 90s, I know there are dozens of distros and even I don’t have the patience to try them all.

Why Omarchy?

First, because it made the right choice of base distro: Arch Linux. I consider it the best distro out there today for two reasons: it has very little “bloat” (it doesn’t install a bunch of stuff you’ll never use, like Ubuntu, Fedora, Mint, Deepin, or any of those other “beginner-friendly” distros).

Second, Arch Linux has the AUR, which is a repository of user-made packages that has basically everything. You don’t need to go hunting for third-party repositories or install things manually. With a single command, yay, you install everything. There’s none of that apt-repository add nonsense or having to make install or anything like that. The AUR manages all of it for you.

Third, it installs Hyprland (which I was already using and liked), with very good configs, and a very good package selection. Everything I would install manually myself. So it’s a thousand times easier to get what would take me much more work to do on my own. Check my series of posts about Omarchy to see those options.

Linux for Beginners?

Beginner at what?

I hate this question. If you’re really an amateur user, not a programmer, maybe you’re an accountant, maybe you’re just a teenage gamer. The first question I ask is: why do you want to use Linux?

Let’s say it’s because you heard it’s more secure (and it actually is). Then it doesn’t matter, any distro will do. Install Ubuntu, install Manjaro, install Garuda. It makes no difference, because you’ll never deal with anything under the hood. You’ll open Chrome, open Steam, and that’s it. The rest is going to be web apps.

Let’s say it’s just for gaming, then install Bazzite on your mini-PC or handheld. Or just install your games on a separate Windows box just for gaming like I did. Whatever.

Or just stick with Windows or macOS. If you’re a total amateur, you’re probably going to use the same weak password for everything, and click on WhatsApp links without checking who they’re from. It literally makes no difference which OS you use. No security from any OS will protect you from your bad habits and ignorance.

If you’re a beginner at programming or tech, then I have no mercy: learn Linux properly. You want to be a professional, be a professional, learn the right way: learn to have 100% control over your own machine. There’s no step-by-step or tutorial for that. It’s something you’re going to do continuously for the rest of your life. I’ve been in this field for over 30 years and I still learn new things every day.

Hardware

The BIGGEST problem anyone is going to face, with ANY distro, is going to be hardware support. And that’s why you shouldn’t just follow what someone recommends to you:

Nobody has the same PC as you.

What’s your notebook? A Lenovo? A Dell? A Positivo? From what year? Which model?

Everything varies: which Wi-Fi and Bluetooth device? Which graphics card? Which firmware is running? With which power profile support? Do you need FIDO2 devices for things like a fingerprint reader? Hardware keys? Does your machine have TPU? Will you need Secure Boot?

I don’t know. You are the one who has to know.

A practical example, I have an Asus Zephyrus G14 notebook that I use with Windows because it only lives in my workshop to run Bambu Studio to control my X1C 3D Printer. I haven’t gotten around to installing Omarchy on it, but let’s say I wanted to. Would it work?

Fortunately there’s a page on the ArchWiki dedicated to this model. It looks like everything works “out-of-the-box”. But if it were the previous year’s version I’d have to check extra items. There are Wi-Fi issues, for example.

Each different machine will have different problems.

Live Env and Ventoy

“So what do I do, you [censored]?”

That’s why pretty much every good distro offers an installation ISO that comes with a live environment. I’ve seen a lot of people on Windows who have trouble knowing what to do with an ISO. It’s very simple.

The easiest program to use is Balena Etcher. You download the file with the .iso extension, whether from Ubuntu, Mint, Elementary, etc (ALWAYS FROM THE OFFICIAL SITE!!!!). Open Balena and there are only 2 steps: select the image (the ISO file), select the drive (your pen drive, careful not to pick your HD!), and done.

Now just boot your PC and go into the BIOS to select the pen drive to boot from, or use a key like F12 (varies from BIOS to BIOS) to have UEFI select your pen drive.

That will boot the Live Environment straight from the pen drive.

Most distros start by opening a “Welcome” screen similar to the one above. This installer app is called Calamares and everyone with a graphical installer uses it. That’s why it looks similar across all of them. It’s the same step-by-step. If you’ve installed one distro, you’ve installed them all.

But you don’t have to follow Calamares. You can close it. And now you’re already in the graphical environment of the distro you chose to install. USE IT. Try to configure your Wi-Fi, try to pair your Bluetooth headphones or mouse, try to turn on the webcam, put in a micro-SD card and see if it shows up. Try to browse the web and feel the performance.

If at this point you can do all the basic things, it means the chances that everything will work are high. If at this point you already start having problems, like not being able to connect to your Wi-Fi, that distro is probably going to give you a headache. Start by going to Google and see if somebody has already solved the problem for your notebook or PC model, before continuing with Calamares.

Let’s say you decided to take the day to test several distros to see which one runs best on your machine. Great call, but you’ve probably figured out that it’s going to be a huge pain to have several pen drives, one for each distro. Or having to keep going back to Windows and using Balena to overwrite a new distro on your only pen drive.

You don’t need to do that.

You just have to first download and install Ventoy on your pen drive. Check the documentation on their site, but it’s ridiculously simple.

After installing it on your pen drive, now just copy ALL THE ISOS you want at once onto the pen drive. When you boot from it, you’ll enter the Ventoy menu, which lets you pick any of the ISOs you copied there. If you didn’t like the current distro, just reboot into Ventoy again and pick another ISO. It’s that simple.

Distrobox

Let’s say you’re a programmer, or a devops, or any tech professional. Your concern isn’t so much the graphical interface (which you can test with Ventoy), but whether the OS infrastructure is going to work with your development requirements.

Let’s say you use Fedora. I wonder, if I go to Mint, will it have the K8s packages the way I need them? Does it support the Java version I use? If I build a .deb package on my Fedora, will it install properly on Ubuntu?

Having to dual boot or install a VM feels too heavy, too much work, just to test 2 command lines, for example.

That’s what Distrobox is for. It needs Docker or Podman already installed on your machine. But after that you just do:

distrobox create -n debian-test --init --image debian:latest --additional-packages "build-essential"

Once the box is created you just enter it:

distrobox enter debian-test

Done, you’re inside Debian, super fast. Since it’s a Docker container, you can map directories on your local machine into the container, so everything stays integrated. And the most important thing: it loads super fast, because it’s just a Docker container.

The Quick Start guide explains all of that and has this video with a tour to demonstrate how it works:

Conclusion

Seriously. With Distrobox there’s no excuse not to test another distro in 2 minutes. Stop wasting time sending DMs to “influencers”. See for yourself! If you’re not capable of doing that, maybe you’re in the wrong profession.

Every “dev” or tech professional, whether devops, cybersec, data analyst, blah blah blah, whatever the trendy title is these days, MUST have control over their own machine. MUST know how to deal with security (that’s why I wrote posts about Vaultwarden, Cloudflare, SSH, etc).

IT’S YOUR RESPONSIBILITY!

Don’t outsource your responsibility to others. Don’t look for validation. Be promiscuous and test whichever distros you want, and do whatever you want on those distros: they are yours! There’s no such thing as a “distro for beginners”, “distro for devs”, “distro for devops”. A distro is a distro. Linux is Linux. It’s all the same, what varies is your skill. If you don’t have the skill: earn it! Learn! Break your head over it! Pull all-nighters tuning configs! Read the official documentation! Don’t waste time thinking you’re going to learn on social media. You won’t.

I’ve been using Linux since the early 90s and I don’t stick with Slackware just because it was the first one I learned and I feel a need to validate my first choice. I use whichever ones I want. Right now, I had my own Hyprland setup, and I decided I wanted to learn and use Omarchy. I spent the week banging my head against it, and wrote half a dozen blog posts. And now I’ve learned. I know Omarchy: one more for the collection.

Just head to the official site and click “ISO” to download. Use Rufus or Balena Etcher on Windows (or Caligula on Linux) to burn it to a USB stick and boot from it. From there, follow the step-by-step and in less than 5 minutes you’ll have everything installed.

As I explained in the first article, I did it differently: I installed pure Arch Linux, Desktop style, with Hyprland + SDDM. Then I installed Omarchy using the manual command line:

curl -fsSL https://omarchy.org/install | bash

You can do it either way. The second gives you more control, but after gaining more experience and reading the install scripts, I recommend downloading the Omarchy ISO itself. It really is easier.

Limine vs Grub

The reason I went the manual route was because I wasn’t sure if Omarchy supported BTRFS rollback via snapshots. I had heard that the Limine bootloader didn’t support that. But I was wrong: Omarchy installs Limine with Snapper support (which is similar to Timeshift, the one I usually use). Read ArchWiki section 6.2. So this should be a superior option to my GRUB+Timeshift setup that I talked about in the first article.

Since I already installed it manually, I’ll keep things as they are because in practice it’s the same thing. But if I were installing again, I’d go with Limine+Snapper just to try it out.

This means there’s support for snapshotting your entire filesystem with BTRFS before a package update, and if something goes wrong, you can reboot and roll back to a previous snapshot. That gives you peace of mind so you don’t lose a whole day trying to fix something if an important system package ships buggy or corrupted. That’s the most important feature.

SDDM vs UWSM

Another thing I noticed was the login manager. On pure Arch, it installs Hyprland by default with SDDM, the same one KDE uses.

Omarchy uses UWSM, which auto-logs you in with your user at boot. So there’s no login screen, it just opens Hyprland automatically.

“But isn’t that insecure??”

No, because the Omarchy ISO pre-configures your SSD with LUKS, below the filesystem.

For those who don’t know, LUKS stands for Linux Unified Key Setup, which provides full-disk encryption. Its advantage over Windows BitLocker is that it’s filesystem-agnostic. In other words, it works with BTRFS or EXT4 or any other, because in the boot sequence, after the bootloader (whether Limine or Grub), it loads before the filesystem. It’s a block-level encryptor.

So when you boot your system, it first asks for the passphrase to decrypt your disk. Then the filesystem opens and the Linux kernel can continue the normal boot with the disk unlocked. So you are always forced to type your strong user passphrase at boot to decrypt the disk.

That’s why typing a password again at a login manager would be redundant and unnecessary, and I imagine that’s why they chose UWSM instead of SDDM.

Especially on a laptop, or in situations where other people live with you, it’s essential to make sure your disk is encrypted, no matter the operating system. Say you go out to work or travel and your laptop gets stolen. Without encryption, it’s game over, regardless of whether you have a login manager. It doesn’t protect your data. Anyone can just pull the SSD from your laptop, plug it into another computer, and boom, they can copy everything by booting as root.

With encryption, without the passphrase to decrypt it, accessing your data is impossible. Truly impossible, because on any modern computer from the last 15 years, the CPU ships with hardware-accelerated instructions for AES 256 encryption.

Getting a bit more nerdy: the decryption key is not your passphrase. During the install process, a new stronger and more secure key is generated using a key derivation process (KDF - Key Derivation Function), nowadays using Argon2id, previously PBKDF2. I explain this in this video:

So when you type your passphrase, what actually happens is it decrypts that secure key, and it’s with that secure key that your disk is encrypted. That’s why you can’t brute-force decrypt your data.

Plus, AES 256 is one of those encryption algorithms that’s quantum resistant. Even if a quantum computer were possible (it isn’t), not even that could decrypt your disk. That’s the level of security.

“But won’t it be slower?”

No. It’s practically imperceptible, because AES, as I said, is hardware-accelerated by your CPU and doesn’t depend on operating system software. In day-to-day use, you’ll barely notice. Performance is practically the same. There’s no reason not to enable encryption, especially on a laptop.

In my personal case, where I installed it on a desktop PC that I control myself on a secure local network, because I know how to implement network security, it’s not an issue. My most important data lives on my NAS (which is encrypted), in backups (which are encrypted). I don’t have sensitive data on this PC, and the little I do have sits in files encrypted by Veracrypt on a separate sub-volume.

That’s why I didn’t enable LUKS on my PC. And I kept the SDDM that pure Arch installed. Except it’s REALLY ugly by default, so here’s a small tip: install either the sddm-sugar-dark theme or dark-arch-sddm. I prefer the second one because it’s more minimalist and looks like this:

I customized it and swapped the Arch logo for the Omarchy one, and that was it.

Conclusion

I’ll say it again: only after installing manually did I see how Omarchy installs things, and today I prefer the Omarchy way. If I were installing from scratch, I’d use the Omarchy ISO and keep it with Limine+Snapper and Hyprland+UWSM, with snapshot rollback support, full disk encryption, and automatic login into Hyprland.

You can tell the people behind Omarchy have experience and have already picked components that make sense to work together in the most convenient and secure way possible. I was worried that, being a new distro, maybe they hadn’t given this much thought, but I’m happy to say I was wrong.

Use the official Omarchy ISO.

Even if you don’t use Omarchy, I recommend installing LazyVim. Just do this:

# required
mv ~/.config/nvim{,.bak}

# optional but recommended
mv ~/.local/share/nvim{,.bak}
mv ~/.local/state/nvim{,.bak}
mv ~/.cache/nvim{,.bak}

git clone https://github.com/LazyVim/starter ~/.config/nvim

rm -rf ~/.config/nvim/.git

nvim

That’s it. For those who don’t know, NeoVim is a more modern fork of the old Vim (hence the command is nvim, leaving vim reserved for the old one). It replaces the old VimScript with Lua scripts and has many optimizations and better quality-of-life features. These days, there’s no reason to keep using old Vim.

Using Lua, you can configure Nvim any way you want. But configuring everything from scratch is a lot of work. It’s a good exercise, but practically speaking, it’s not worth it day to day. Better to install a pre-configured setup like the old LunarVim, which I used before and even recommended in some Linux videos on my channel, or AstroNvim, or LazyVim, which is currently my favorite. Any of them is a good start and it comes down to personal preference.

Each plugin they install has many features and its own key combinations (hotkeys) that you need to read in the documentation to know what does what. I recommend going to the plugins section of the official site and reading them one by one. There’s a lot of stuff you wouldn’t even expect, and all of it is very useful.

LazyVim on its own already helps a lot because it opens pop-ups documenting some of the hotkeys. For example, what’s called the Leader command in LazyVim is the “space bar”. When you press it, this context menu appears:

From here, if you type, say, “b”, another context menu shows up:

And if you type “b” again, it switches to the next file already open in the Buffer. Buffer is the Vim name for where already-opened files live. Deleting from the Buffer is the equivalent of “closing the file”.

Next time, you won’t need to look at the menus. Just type quickly in one go: “Space+b+b”. That’s how you memorize the commands you use the most.

Some commands worth learning right away: Space+Space (twice), which opens the menu for opening files. Type a few letters of the file name and it filters dynamically:

Or “Space+e” to open the NeoTree Explorer. Type “?” to open a popup with the commands you can use to create new subdirectories or files within the subdirectory:

Once you learn the other commands and plugins, you’ll notice you don’t even need to open NeoTree. It’s more for when you want to explore visually. For day-to-day work, commands like “:e” should be enough. By the way, “:” (colon) is the command for executing NeoVim functions. For example “:q” is quit, “:w” is write, and “:wq” is write and quit at the same time.

If you want to learn NeoVim more deeply, I recommend the YouTube channel of my friend Eustáquio Rangel, a Linux, Rails, and Vim veteran who teaches NeoVim from scratch (without LazyVim).

Now, let’s say you’ve already learned the basics of NeoVim and LazyVim, and now you want to start working on your PHP, Java, C#, Ruby, Python, or whatever projects. You’ll notice that LazyVim doesn’t have any functionality for any of them.

What do you do now? Install VS Code?? NO!!

That’s because you haven’t run :LazyExtras yet.

Type it exactly like that and watch this:

This window looks complicated but it’s just a list of plugins split into sections. At the top you see the plugins already installed and enabled. If you don’t want any of them, just use the arrows to move the cursor down to one of them and press “x” to unmark it. But leave that section as is. Let’s scroll down to the “Languages” section:

This is the section where all the languages you can enable support for live. Just scroll down with the arrows and mark with “x” which ones you want to install. And there’s everything: Angular, Vue, Erlang, Elixir, Rust, Zig, Haskell, and much more.

Next to each language is the group of individual plugins it will install. To know what each one does, type their names into Google and find the documentation page, where you’ll find hotkeys and extra configurations you can set.

With this you gain things like Linters, syntax highlighting, LSP, snippets, and much more.

And if you want to install additional plugins that aren’t listed, you can add them manually. Read the Adding Plugins section in the documentation.

LazyVim + LazyExtras covers 90% of everything you need for day-to-day software development. It’s lighter and faster than VS Code, uses way less memory, and will be much better especially on older machines. Don’t be lazy about learning Vim. A real programmer shouldn’t stick with VS Code just because they’re too lazy to learn a few extra hotkeys.

The Problem

Before, to contribute to the blog you had to:

1. Install Hugo Extended
2. Install Go
3. Install Ruby
4. Set up all the dependencies
5. Generate the post index manually

This created barriers for new contributors and could cause conflicts with other installations on the system. A nightmare.

The Solution: Docker

Now all you need is Docker and Docker Compose. Everything else runs inside isolated containers.

Quick Setup

# Clone the repository
git clone https://github.com/akitaonrails/akitaonrails.github.io.git
cd akitaonrails.github.io

# Start the environment
./scripts/dev.sh start

# Open the blog
open http://localhost:1313

Done! The blog is running and you can start contributing.

Useful Commands

The project includes scripts that make development easier:

# See all available commands
./scripts/dev.sh help

# Create a new post
./scripts/dev.sh new-post "Título do Meu Post"

# View server logs
./scripts/dev.sh logs

# Generate the post index
./scripts/dev.sh generate-index

# Stop the environment
./scripts/dev.sh stop

Creating a Post

Creating a new post is dead simple:

./scripts/dev.sh new-post "Como Contribuir no Blog do AkitaOnRails"

The script automatically:

• Creates the directory structure with the current date
• Generates an index.md file with basic front matter
• The Hugo server reloads automatically

Structure of a Post

The created file will have this structure:

---
title: "Título do Post"
date: "2025-08-29"
draft: false
description: "Descrição do post"
tags: [tag1, tag2]
categories: [categoria]
---

Conteúdo do post aqui...

Advantages of Docker

For Contributors

• Fast setup: Docker is the only requirement
• Isolated environment: Stays out of the way of your local system
• Hot reload: Changes show up automatically
• Reproducible: Works the same way for everyone

For the Project

• Fewer issues: Consistent environment
• More contributors: Lower barrier to entry
• Maintenance: Easy to update dependencies

How It Works

The Docker environment includes:

• Hugo Extended: Static site generator
• Go: For Hugo modules
• Ruby: For the index generation script
• Volumes: For hot reload of files

The docker-compose.yml maps the local directories into the container, so when you edit a file, Hugo detects the change and reloads automatically.

Local Development (Alternative)

If you prefer to skip Docker, you can still install everything locally:

# Generate the index
cd content && ruby generate_index.rb

# Run the server
hugo server --logLevel debug --disableFastRender -p 1313

But Docker is way more practical!

Next Steps

1. Test the environment: Run ./scripts/dev.sh start
2. Create a post: Use ./scripts/dev.sh new-post
3. Explore the code: See how to customize layouts
4. Contribute: Open a Pull Request

Tip: The Docker environment automatically saves your changes and reloads the server. Just edit the files and watch the changes in real time! 🚀

See the full text at this link

He gives tips on how to “tune” this new model, mostly for math-related questions, and I started wondering whether we can tune it for software development. Before more advanced researchers yell at me: this is my first time messing with the parameters of an LLM, so if you want to add context in the comments, you’re welcome.

Let’s go. First, what are these TopP, TopK and everything else Ivan mentions in his tweet? They are KEY SAMPLING parameters. It’s a group of parameters that control HOW the model selects the NEXT TOKEN and goes on completing the text (giving the “answer”), based on its vocabulary and the probability distribution it calculates. The most common ones are exactly temperature, top_p, top_k and sometimes min_p or repeat_penalty.

I always say: an LLM is a next-word generator, a text completer based on probabilities. When the LLM processes your input (your context, chat history and the next question), it needs to calculate a probability “score” for every word or sub-word (token) across its entire vocabulary. Imagine a gigantic model, it needs to recalculate everything all the time, for every next word.

Sampling parameters tell the model “how to choose the next token” from the list of probabilities. Without these parameters the model would use a “greedy” decoder (too ambitious). That means it would just pick the token with the highest probability every time. And that leads to a repetitive, unnatural-sounding result. Sampling adds a kind of “controlled randomness” (remember? I always say there is randomness baked in, the answer is never “right”), and that makes the response more “interesting” to a human being (who is easily fooled). Here are some of the parameters:

Temperature

Controls randomness, which many people call “creativity”. It essentially makes the distribution hotter (more spread out and flatter) or colder (with more peaks around the same tokens). The higher the temperature (up to 1.0), the more it increases the probability of picking tokens that had lower calculated probabilities. The lower the temperature (down to 0.0), the smaller the chances for tokens with lower probabilities, and the more “greedy” the result gets (less “human”).

For code, crank it too high and you start getting “hallucinations” (which are basically increased randomness) and code that doesn’t make sense. If it’s zero, it gets very “boilerplate”, repetitive, using very common patterns and can potentially end up in an infinite loop with no answer (because it can’t pull anything different).

The tweet suggests 0.6, which is moderate. But in my tests, a temperature that high already started giving me some weird code. Out of nowhere it would change a variable name. Out of nowhere a Chinese character would appear in the middle of the code (literally). I think 0 is too low, but 0.1 is enough, maybe 0.2.

You can change this in the ~/.aider.model.settings.yaml file before loading the model (these parameters can be readjusted at startup):

- name: ollama_chat/qwen3-dev:latest
  extra_params:
    temperature: 0.1
    num_ctx: 40960

top_p (Nucleus Sampling)

Here it starts to get complicated. This top_p is used to select tokens from the smallest set of tokens whose cumulative probability exceeds this “p” limit. The model then samples only from this reduced set.

The model sorts all the tokens by their probabilities in descending order (from highest to lowest). Then it starts adding up their probabilities until the sum is greater than or equal to top_p. All the tokens included in the sum form the so-called “nucleus”, and from that set it samples the next token. So it’s a draw among the tokens with the sum(x) highest probabilities, more or less. “Pick one of the winners, but not necessarily THE winner (which would be greedy)”.

top_k

Consider only the “k” most likely tokens. The model samples only from this reduced set of the top K highest probability tokens. That really means “pick one out of the Top 10 best”. The higher the K, the greater the diversity, the lower it goes, the more greedy.

And this is relative, top_k and top_p work together. This configuration helps anchor the selection to the “most likely” tokens while still allowing top_p to filter out the lower probability ones. It prioritizes plausibility (top_p) while restricting the total number of sampled tokens (top_k). It helps keep the result focused on the most likely “correct” answers (but again, it’s a draw/sampling).

min_p

Filters out tokens whose probability is less than “min_p” times the probability of the most likely token. Before sampling, the model identifies the token with the highest probability (P_max), then removes any token with a probability (P_token) that is lower than P_max * min_p. Sampling then happens over the remaining list (which will be further filtered by top_p and top_k).

This prevents the model from choosing tokens that are “extremely unlikely” relative to the most obvious choice.

repeat_penalty

This discourages the model from repeating the same tokens that have already appeared recently in the conversation history or generated text.

Before sampling, the probability score of tokens that have been seen recently is reduced, dividing by this repeat_penalty (with values greater than 1, since dividing by 1 is itself, so it keeps the same probability).

If you leave it at 1.0, it can start repeating the same answers or the same code, even the wrong ones. If it’s too high, well above 1.0, the response can sound unnatural, since sometimes it really needs to repeat something to re-explain. A moderate value somewhere around 1.1 up to just under 1.2 tends to be more appropriate so it doesn’t punish too much what’s already in the history.

num_predict (max tokens to generate)

The absolute maximum number of tokens the model will generate as a response. If it goes over, it truncates. If it’s too small, especially for a code response - which can be long - it can truncate too much and leave the answer incomplete. If it’s too big it will greatly increase processing and demand way more machine resources and more time, and it can be wasteful.

A value of around 32 thousand tokens leaves plenty of room for tokens. You have to test, and it varies case by case for the type of response you expect and what each model supports.

Recommended

Knowing all this now you can also read Ivan’s tweet and understand it. He recommends Temp 0.6, TopP 0.95, TopK 20, MinP 0.

I fiddled with it a bit more. And I think that for code, Temp has to be in the 0.1 or 0.2 range. I also think a repeat_penalty of 1.1 is worth it to avoid unnecessary repetitions, especially of code. Again, you have to test. These are empirical numbers, not exact ones.

I created a project on my GitHub with a complete model file that not only implements these parameters but also pre-configures a system prompt to bias the model towards being a code assistant first. Here’s my prompt:

SYSTEM """
You are a highly functional AI assistant specializing in software development tasks.
Respond to queries about coding, algorithms, debugging, system design,
and programming languages/frameworks.
Provide clear, accurate, step-by-step reasoning and functional code examples.
Always format code snippets using markdown triple backticks (```language ... ```).
Aim for comprehensive and correct technical assistance.
Never suggest changing code unrelated to the question topic at hand.
Restrict yourself to the minimum amount of changes that do resolve the problem at hand.
Avoid renaming functions or variables unless absolutely necessary, 
and in doing so make sure if there's anyone calling the old names, 
for them to be renamed to the new names. Never leave the code in a broken state. 
Pay close attention to correctness, not just answering the quickiest and dirtiest code to solve the problem.
"""

To make this file, first I pulled the original Qwen3 Modelfile with this command:

ollama show qwen3 --modelfile > Modelfile

It’s important to do this because, from what I understand, modelfiles don’t inherit from a previous one. They don’t work like a “FROM” in a Dockerfile, where you continue a new image from a previous base.

After editing it with my adjustments - which is already on my GitHub, just create a new model:

ollama create qwen3-dev -f qwen3-dev.modelfile

And it will show up in your local ollama. Check with ollama list:

❯ ollama list
NAME                                            ID              SIZE      MODIFIED
qwen3-dev:latest                                fe03dfae5484    9.3 GB    About an hour ago
qwen3:32b                                       e1c9f234c6eb    20 GB     2 hours ago
qwen3:14b                                       7d7da67570e2    9.3 GB    8 hours ago
qwen3:latest                                    e4b5fd7f8af0    5.2 GB    8 hours ago
qwen2.5-coder:7b-instruct                       2b0496514337    4.7 GB    25 hours ago
....

See qwen3-dev:latest? That’s our new model with parameter adjustments. In aider just use it directly:

aider --watch-files --model ollama_chat/qwen3-dev:latest

Remember to adjust the .aider.model.settings.yml as I showed above.

I haven’t done long tests yet, but I decided to play with the 14b model as the base along with these adjustments. The base model already impressed me and at least my adjustments didn’t break anything. I kept doing the same refactorings and unit tests on my little educational project and pushed another pull request

I think Gemini 2.5 Pro Exp is a little better, but again, not by a very large margin. And in some cases (like refactoring), I think I prefer the code generated by Qwen3. Compare it with the code I got from Gemini in this other pull request

With Gemini I had to explain less and it gave fewer errors, but both managed to do what I asked all the way through without breaking the main program. Qwen3 looks good enough for me to want to use it. With the advantage that even being the medium model, with 14 billion parameters (which runs on my 24GB of VRAM with room to spare), it still delivers very good and clean code results. And better: it runs MUCH, but MUCH faster than Qwen2.5 32b.

For those who have GPUs with less VRAM, say, a 3070 or 4070 with 16GB, you can use the even smaller 7b model. I tested qwen2.5-coder:7b and had excellent results, so I imagine the Qwen3 7b should be even better and much faster. Speed that is comparable to Claude or Gemini, which are much larger and run on much beefier machines than an RTX 4070.

Running my qwen3-dev, in my monitoring my CPU stayed idle most of the time and the GPU was above 90% the whole time, consuming almost 400W constantly, holding a temperature of 73 degrees (which is good).

I even had a small incident where my PC shut down out of nowhere, because the temporary extension cord I was using couldn’t take it and died. Combined with the CPU and my other devices plugged into the same outlet, it was consistently pulling 1000W from the wall for hours. Playing with A.I. uses A LOT of energy, with the air conditioner on because just to dissipate all of this, my apartment gets 1 to 2 degrees (my rough guess) above normal. You can actually feel it a bit warmer lol

But that’s it, I hope you got a sense of how things actually work under the hood. There’s no magic: it’s next-word generation, based on a semi-random draw from probabilities.

Now you know.

Update: this post is now obsolete. I replaced the manual setup with a cleaner containerized project: akitaonrails/aitrepreneur-docker. It runs Aitrepreneur’s stacks locally in Docker, with pinned versions, persistent models, and pre-loaded workflows. Check the README for details.

In the previous post I explained my little project to spin up ComfyUI pre-configured and pre-loaded automatically using Docker Compose. Assuming you already have everything up and running, now it’s time to actually understand this beast called ComfyUI a little.

I’m no expert either, but I thought it would be cool to explain a few concepts that many people overlook.

Pre-Trained Models

Every GPT out there, or Stable Diffusion or others, loads a vector database into the GPU’s memory, into VRAM, in order to process. They are HUGE models, called 7B, 70B, 100B, etc. The “B” stands for “Billions of Parameters”. Parameters have no usable definition outside of math, they are simply numbers. Those numbers represent “something” inside millions of dimensions inside that giant file.

In a VERY ROUGH way, I think of them as compression artifacts. You take PETABYTES of books, images, texts, posts, etc, break it all into tokens and find “relationships” between one token and many other tokens, and you keep “positioning” them in space, but not in 3 dimensions, in millions of dimensions. AI models are “Vector Space Models” or VSMs, more or less like the index of an Elasticsearch if you’ve ever played with relevance-based text search, or any “Full Text Search” plugin in Postgres or MS-SQL. They’re all VSMs.

Here’s how I think about it: it’s as if the training process - the SUPER EXPENSIVE part, which takes MONTHS - takes all the information that’s fed in and compiles a new “dictionary” for a new “language”. Now, when you “talk” to a GPT, first it needs to transform your text from your language into this internal “language” of its own, which is what we call an “Embedding”.

Any data can be transformed. Audio can be converted into text and from text into embeddings. Videos can be broken down into series of images with temporal information. Images can be deconstructed into elements like luminance, chrominance, etc. In the end, everything can be deconstructed into data structures, there’s no magic.

Image generation models are trained differently. There are several focuses, focus on facial sharpness, focus on pose accuracy, focus on different styles like cartoon or painting, focus on categories like animals or objects. That’s why there are dozens of models out there and lots of “loras”.

To generate an image from a prompt, first you need to decode your prompt into an embedding, and that’s what things like a TEXT ENCODER in ComfyUI are for.

In the specific case of AI for images, the way I understand it is that they use something called a “DIFFUSION” model both to deconstruct the original image and to reconstruct a new image. It’s not intuitive, but the reconstruction doesn’t start on a blank canvas, the way it would for a human illustrator. It starts with an image filled with random “noise” like this:

The model starts from this noise and through a process called DIFFUSION it begins to redraw the image backwards, until it emerges from the chaos and arrives at an image.

What I “THINK”, what I “GUESS” is happening - without having read any paper, pure laziness - is that we try to influence this initial noise. For example, by extracting features from the image like a depth map, which looks like this:

The original photo looked like this:

.jpg)

Extracting a Depth Map is an ALGORITHM, it’s not “AI”. Any Photoshop or Premiere out there can do this with one hand tied behind its back. But the point is to explain that there’s much more information in an image than what you - untrained as you are - can see is there.

Another well-known type of ALGORITHM is Canny Edge Detection, which produces an edge map, making it easier to know where something starts and ends in the image:

So it goes more or less like this:

• just as a text is “converted” into an Embedding, vectors that capture the “essence” of the meaning of the text, dependent on the VSM of the pre-trained model, an image is “converted” internally into a LATENT, which because it’s an image is a “space” (that’s why people talk about Latent Space). We can’t “visualize” Latents, because it’s an internal representation that depends on the U-NET, the pre-trained model, the neural network that learns to “denoise” the Latent.
• An image U-NET is roughly similar to a text model like GPT or LLaMA, the pre-trained, read-only model that will be used to produce the final result.
• A GPT response is a continuation of the context of the previous conversation. It’s not “answering” you directly, it’s just “continuing” the text of the conversation and, by chance, due to training, the result “looks like” a response. In the case of images, we start with a randomly noisy image and through a process of removing and adding noise, it gradually “rearranges” the Latent into an image we can recognize.
• There is a “Scheduler” that decides how much noise is added or removed at each time step. And there is the concept of a DIFFUSION MODEL, which is more or less the processing “pipeline”.
• We can control the process by adding a text prompt, which is decoded into an “embedding” using a Text Decoder that usually has names like “CLIP” or properly a Transformer (such as LLava). These embeddings go into the U-NET via cross-attention layers, steering the “denoising” toward the meaning of the prompt.
• On top of that we have CONTROLNET, which is a second parallel network that adapts the process to extra conditions. It’s a copy of the U-NET architecture (with frozen weights) that receives extra inputs, like Canny Edges, or Depth Maps, pose skeletons (via OpenPose), etc, and learns small adjustments to INJECT into the main maps of the U-NET.
• During the denoising process, ControlNet activations are merged with those of the U-NET, forcing the process to respect the conditions we passed in.

So the U-NET is the “generator”, the Diffusion Scheduler orchestrates the process, text encoder and controlnet both influence the U-NET, and a VAE is used at the end to convert a latent space into an actual image that we humans can actually see.

VERY, VERY ROUGHLY. That’s more or less how I understand the process. And the way I see it, ComfyUI exposes several of these steps in the form of “PROGRAMMABLE NODES” that we can parameterize and tweak to influence how we want the final image to come out.

Beyond numerical parameters, these Nodes also let us choose which pre-trained model files we want to use for each stage. It’s all binary VSMs, but for different uses, which is why many of them have the same extension as I explained, but they live in different sub-directories. So each Node can find only what matters to it.

Taking my photo as an example, this isn’t exactly it but just to illustrate, it helps me think that those maps I showed influence the “noisy” image in a non-random direction, like this one I grabbed from an intermediate stage of the workflow I’m running:

If you strain your eyes, you can see the influence of the previous images, and the Diffusion model keeps doing the “denoising”, being “interrupted” by the ControlNet. It’s as if you were drawing and had a person next to you who every now and then erases what you did, or draws on top, and you keep adapting. So in the end it becomes a “collaborative” job between the two. If it were only the U-NET, it would generate a brand new image quite different from the original, but the ControlNet is the “client” that keeps nagging in your ear “that’s not how I want it, change it”, until it arrives at an acceptable result.

On top of that, a U-NET isn’t great at generating very high resolution images. The ideal is to generate small images, 512 pixels, 1024 pixels, but nothing bigger. But that would be useless for professional use. That’s what UPSCALE MODELS are for. If you read my article from yesterday about Video2K I explain that I pick a model there that’s good for temporal coherence in video. But there were other models that are better for “STATIC IMAGES”, or photos. And we can use them in ComfyUI.

After the new small image is generated by the U-NET, we can then use it as input to a second “UPSCALE” pass using a model like RealERSGAN, and go from a 1024 pixel image to 2160 pixels, essentially 4K. It’s different from enlarging the image in Photoshop, where everything ends up “soft” and blurred. Since it’s also another AI model, it’s trained to “redraw” at higher resolution. And we can add this to the ComfyUI workflow as well.

More than that, ComfyUI also supports Nodes with models like Tencent’s HunyuanVideo, which I introduced in another article from yesterday, about FramePack. In fact, we can do the same thing FramePack does but from a ComfyUI workflow: generate a video from an image, using the same model. FramePack is infinitely easier to use, but ComfyUI is the Swiss Army knife of AI: it does EVERYTHING, which is also why it’s infinitely more complicated and you need to put in serious effort to learn how to use it.

With what we’ve covered so far, take a look at the workflow I used (it’s zoomed out, you can dynamically zoom in):

You can see these intermediate steps using PREVIEW Nodes, so this is more or less how we can use ComfyUI to do a lot of advanced stuff. As I said, I myself haven’t even started scratching the surface.

Let’s now summarize some of the concepts used in ComfyUI:

1. Checkpoints (Base Models)

What they are:
These are the main Stable Diffusion models (e.g.: SD 1.5, SDXL, Flux). They contain the entire model architecture:

• Text Encoder (CLIP)

• Diffusion Model (U-Net)

• VAE (Image Decoder)

What they’re for:
Generating images from scratch. Each checkpoint has a different “style” (realistic, anime, etc).

Examples:
flux.safetensors, realisticVisionV60.safetensors, anythingV5.safetensors

2. VAE (Variational Autoencoders)

What they are:
Component that decodes images from the latent space (the format the model understands) into visible pixels.

What they’re for:

• Improving details and colors

• Some checkpoints require specific VAEs

Examples:
vae-ft-mse-840000.safetensors, animevae.pt

3. Text Encoders

What they are:
Models that convert your text prompt into numerical representations the AI understands.

Common types:

• CLIP: Standard for most models

• OpenCLIP: Alternative version used in SDXL

• T5: Larger models for complex prompts

Examples:
clip_vision.safetensors, openclip.safetensors

4. CLIP Vision

What they are:
Models specialized in visual analysis (as opposed to normal CLIP, which is text→image).

What they’re for:

• Creating descriptions of existing images

• Tools like “Image Prompt” (which use the image as input)

Example:
clip_vision_g.safetensors

5. Diffusion Models

What they are:
A specific part of the architecture (U-Net) responsible for the diffusion process (adding/removing “noise”).

What they’re for:

• Training LoRAs

• Advanced reuse workflows

Example:
unet.safetensors

6. LoRAs (Lightweight Adapters)

What they are:
Small files that modify the behavior of the main checkpoint without replacing it.

What they’re for:

• Adding specific styles (e.g.: anime)

• Creating consistent characters

• Adjusting body proportions

Example:
epiNoiseOffset.safetensors, add_detail.safetensors

7. ControlNet

What they are:
Models that impose control over the composition of the image (poses, depth, edges).

Common types:

• OpenPose (human poses)

• Canny (edges)

• Depth (depth)

Example:
control_v11p_sd15_openpose.safetensors

8. Upscale Models

What they are:
Models for increasing the resolution and detail of generated images.

Types:

• ESRGAN: For realistic details

• Anime6B: Specialized in anime art

Example:
4x_NMKD-Superscale-SP_178000_G.pth

9. Embeddings (Textual Inversions)

What they are:
Small files that add new concepts to the model’s vocabulary.

What they’re for:

• Specific artistic styles

• Custom objects

• Artifact corrections

Example:
bad_prompt.pt, easynegative.safetensors

10. Style Models

What they are:
Models specialized in applying visual styles or art “filters” on top of the generated image, without actually altering the basic structure of the content.

What they’re for:

• Thematic colorization (e.g.: watercolor palette, sepia, chroma-key)

• Simulating artistic techniques (oil, gouache, manga linework)

• Unifying aesthetics across series of images (same color and light “mood”)

Example files:

• flux1-redux-dev.safetensors (“Flux Redux” style)

• watercolor_v2.safetensors (watercolor brushwork)

• film_grain_vintage.safetensors

11. SAMs (Segment Anything Models)

What they are:
General segmentation networks capable of isolating objects or regions of interest in an image, producing binary or weighted masks.

What they’re for:

• Creating masks of objects/people for selective application of filters or compositions

• Guiding ControlNets (e.g.: applying diffusion only inside or outside a region)

• Pre-processing references (cropping background, separating layers)

Example file:

• sam_vit_b_01ec64.pth (SAM ViT-B, base segmentation model)

Visual Summary

models/
├── checkpoints/        ➔ Main models (Stable Diffusion)
│     └── *.safetensors, *.ckpt
├── diffusion_models/   ➔ Alternative diffusion models
│     └── *.safetensors, *.gguf
├── loras/              ➔ Style adapters (LoRAs)
│     └── *.safetensors
├── controlnet/         ➔ Composition controls (ControlNets)
│     └── *.pth, *.safetensors
├── vae/                ➔ VAE decoders / encoders
│     └── *.pt, *.safetensors
├── clip/               ➔ CLIP text encoders
│     └── *.safetensors, *.pt
├── clip_vision/        ➔ CLIP vision encoders
│     └── *.safetensors
├── text_encoders/      ➔ Advanced text encoders
│     └── *.safetensors, *.bin
├── upscale_models/     ➔ Super-resolution models
│     └── *.pth
├── sams/               ➔ Segment Anything (SAM) models
│     └── *.pth, *.onnx
├── style_models/       ➔ Visual style models
│     └── *.safetensors
└── embeddings/         ➔ Embeddings / custom concepts
      └── *.pt, *.safetensors

You have to download the right things into the right places. And to make matters worse, as I already said, the files usually have the same extension. So it’s very easy to get confused and drop a text encoder into the clip directory or vice versa. Once again, that’s why I encourage you to update the “models.conf” file and put the right URLs into the right lists, that way it stays much more organized and my Docker setup will pull things into the right places at startup.

Even so, you may still have a few other doubts that I had at the beginning too. For example “Why is the U-NET called a Checkpoint?”

Checkpoints ≈ A Complete Operating System

• Similarity: Just as a commit in Git captures a specific state of the code, a checkpoint is a complete “snapshot” of a model trained at a specific stage.

• Difference: Checkpoints are self-contained (they aren’t “diffs” like commits), each one is a complete model that can work independently.

• Better Metaphor: Think of checkpoints as different versions of Windows (XP, 7, 10) - each one is a complete operating system, not incremental.

So checkpoints kind of resemble, conceptually, a “git commit” - if you’re a developer. Or BTRFS or ZFS snapshots - if you’re an infra/devops person.

LoRAs ≈ Plugins/Extensions

• Similarity: Just as a PR adds functionality to a base codebase, a LoRA modifies the behavior of the base model.

• Difference: LoRAs aren’t “merged” into the original checkpoint, they are applied dynamically during inference.

• Better Metaphor: They’re like Chrome extensions (e.g.: AdBlock) - they add specific behaviors without modifying the browser itself.

Think of it this way: a model has Checkpoints, like commits, so you can “continue” training on top if you need to. At the same time, we don’t have to mess with the main model, we can create separate layers, the so-called LoRas. For example, let’s say a model is having trouble generating your face, no matter what prompt you use or what Nodes you configure.

Instead of that we can use the “dictionary” of the pre-trained model, like Flux or SDXL, and do training with our personal photos and produce a LoRa specific to me. Then we can add a LoRa Node into the workflow and that will result in much better images with your particular face.

There are entire online communities dedicated to this. One example. On the Civit AI site we’ll find lots of models based on existing models, like this Mistoon which is based on SDXL.

It’s a checkpoint. We can sign up on the site and download the file mistoonAnime_v10Noobai.safetensor and put it in the models/checkpoints directory.

Now, in any workflow that has the “Load Checkpoint” Node we have the option to choose this model. But let’s say this model isn’t able to generate a character with a school uniform like in many anime. Browsing the site, we find this LoRa:

The Mistoon model is large, around 6.6GB, but this LoRa - called Mistoon_Anime\ school\ uniform.safetensor which we should move to models/loras - is less than 290 MB, much smaller because it’s a specific training only on images of school uniforms.

Now we can wire the “Load Checkpoint” Node to this other “Load LoRa” Node and choose this LoRa that we know is compatible:

LoRas have to be picked to be used with the models they were based on. As I said before, think of the model as a “language”, if we make a LoRa in German, there’s no point mixing it with a Chinese model, roughly speaking. But this is one way to do fine-tuning so the model you like delivers results no other one can.

One problem I have with the Civit AI site is that you can only download things while logged in. That’s why I didn’t include any of their models or loras in my automatic install script. Unfortunately, in their case you have to manually download the files and move them to the right directories, write it down somewhere, so on another machine you can download and move everything all over again. It’s a pain that I haven’t sat down to fix yet. If anyone wants to contribute a solution for this (without exposing anyone’s login cookies, send a Pull Request).

A Real Example

Your day-to-day with Comfy, being a newbie like me, will go more or less like this: you start by going to Google and searching for “best workflow image to anime ComfyUI”. The first links are usually some Reddit thread:

Sub-Reddits like r/comfyui or r/StableDiffusion usually have news and workflows like this one. Then we go straight to the first comments:

Either that, or we open the workflow directly in ComfyUI and inspect the Nodes, one by one:

We may already have a problem: the Node came pre-configured to load a LoRa called “SDXL_aidma-niji_jini.safetensors” but the link in the Reddit comment downloads an “SDXL_Niji_V6_DLC_LoRa_V4.safetensors”. Searching specifically for the previous one on Google, I can’t find it. But it seems “safe” to use this other one, at least the names are very similar, both are derived from SDXL so theoretically they’re at least compatible. This is the page of that model on Civit AI, so you have to download manually and send it to the models/loras directory, same thing for the AniToon Checkpoint in the Node above. Download manually and move it to models/checkpoints.

Note that on this page it explains that this LoRa was made to work with the SDXL_Niji_V6 model and not with AniToon, which is what the Workflow I downloaded suggests in its Load Checkpoint Node. It’s worth testing with both. Either way, since we’re already on the site, let’s also download the suggested model:

File sdxlNijiSeven_sdxlNijiSeven.safetensors, 6.5GB, move it to models/checkpoints, are you all getting the process? Download, move it to the right place, reload the workflow in the browser and now it shows up, we select it:

By the way, I think it’s intuitive but for those who haven’t figured it out after opening the ComfyUI interface:

• left mouse button selects Nodes
• middle mouse button drags the canvas
• scroll wheel zooms the interface

Now then, let’s pick these two to test:

Taking advantage of this same image, notice in the left corner a Florence2 Node, which is a Microsoft LLM (and my Docker script already installs it for you). I can’t show all the related Nodes but these are the main ones explaining what it’s for:

The ideal in image generation is to write the longest and most detailed prompt about the original image that you can, but most people just write some garbage like “person smiling standing up” and think that’s enough. The Florence2 model is built to read an image and describe it in text.

Now there’s another detail: many checkpoints or Loras are trained with some activation keyword. So they only kick in if you type those words into your prompt. So this workflow doesn’t need you to type a prompt manually, Florence2 will do that, and every time its text starts with “The image … bla bla bla”, so we have a “Text Find and Replace” Node that swaps that “The Image” for the keywords of Anitoon or Niji: “aidma-niji, niji”.

Are these the right words? I HAVE NO IDEA lol

The workflow already brought these words, but on the Civit AI pages - where it should be documented, it’s not!! So we’re really GUESSING that it should be “niji” since that’s the name of the model and the lora. Pay attention to the keyword, it’s important, otherwise you add the lora and nothing changes and that’s because you forgot it in the prompt!!

There’s more, you have to check that the Nodes for things like VAE, ControlNet, Canny and everything else are populated with files that we have. Usually you use the same half-dozen and I’ve already pre-installed the main ones in Docker. In the image, see that the ControlNet is contronet-union-sdxl-1.0-promax.safetensors, compatible with SDXL, and we’re using Niji which is built on top of SDXL. We just keep guessing like that.

Also notice that it uses Zoe Depth Map to extract the Depth Map and Canny to extract the Edge Map as in the other workflow. You can configure it, in this workflow notice that the Edge Map picked up some weird artifacts in the background, you can adjust it to remove that. That’s why in the previous example the final image also had a window appearing, the model thought it was a window! But for now let’s leave it as is.

Now we can run it:

There’s a huge “RUN” button in blue down at the bottom. If everything is configured correctly, you’ll see that a job has been added to the queue. The interface is smart enough to let you work on other workflows and just keep queueing jobs while the GPU is processing. You don’t have to sit waiting, just leave several queued up and go to sleep.

When it runs, in the interface the Nodes that are processing at any given moment will get a green border, which is good so you know what stage of the process it’s in. And if any Node has an error - because a file is missing, for example - it’ll get a red border, so you have to fix it and run again.

And in the end, here’s one of the results:

Notice how the controlnet maps guaranteed the correct pose. The model interpreted those background artifacts from the edge map as lighting from some window, but in the original photo we can see it’s like the concrete brick of the wall lol but that’s how it is, without knowing, it guesses. And if you run it several times, it’ll always give you a quite different result. Look at another one:

Way off lol But we can swap the SDXL-Niji model for Anitoon. Let’s see one of the results:

Switching to the waiNSFIllustrious model:

This one came out even more off. Something in the maps is making the model assume that I have curly hair, no idea why. But that’s it: you have to tweak the parameters. The result of the workflow I showed at the beginning of the article gave a better result, using the same models.

Of all the Nodes, one of the most important is the “engine” of the process, the KSampler:

This is the guy who runs the show. We give it the model, the prompt, control-net outputs, and it’s the one that iteratively (steps) does the “denoise” of the Latent. Notice that there’s always a random factor (“seed”), a number of steps (25 to 50 is the average), “cfg” (classifier-free guidance) or “guidance_scale”, where higher values pull the image more toward your positive prompt. Denoise is how much noise the scheduler applies (1.0 is full noise, below 1.0 may produce more “artistic” results, you have to test).

Sampler Name is annoying because you’d need to understand the math behind it, but they are the step algorithms, for example euler, ddim, plms and each one has a trade-off between speed and fidelity. In practice: test them one by one and see the results. Scheduler has normal, klms, dpmsolver. Same thing: test them one by one.

As you can see, there are PLENTY of parameters you can play with. But the main flow is more or less this. From there you have to keep learning Node by Node what each one can do and download lots of pre-made workflows to see how people have been solving various problems, which models and loras are the most popular for each kind of application. Anyway, Reddit is your friend. I hope this gave you some sense of direction, I’m also still learning.

More than a year ago, when I made my last videos about A.I. and on the podcasts, I always said I ran everything on my own machine. But I never detailed how. So today I fixed that with several blog posts and little projects on GitHub with Dockerfiles so you can run it on your own machine, without configuring anything difficult.

I finally made a Dockerfile for ComfyUI, which is the best graphical interface for editing image generation workflows. If you’ve ever worked with Davinci Resolve Fusion or Blender Geometry Nodes and the like, workflows are basically node configurations to process your images, audio, video and pipe them through processing steps, not just A.I. ones. It’s like programming visually. That’s why it’s a much more complicated tool than the FramePack I showed in the previous post. You don’t just click and go.

Recently everyone went hysterical with the ChatGPT updates and how it “OH MY GOD” can generate Ghibli anime style images, and they kept spamming the world with idiotic anime-style memes. Online hysteria is really annoying. But as I said, as impressive as it is, that’s all it is: a meme generator. You can’t use it professionally.

I’m tired of trying to upload my own photos, or even generic photos, fictional characters, sometimes drawings of mine, and randomly ChatGPT just refuses to generate the image. Claiming privacy, security, copyright and whatever else it can invent as an excuse. You can’t rely on this for work. Anyone who’s a professional should have full control over the process, and that’s what I’m going to teach today.

To start, clone my GitHub repository and follow the README instructions or do this:

git clone https://github.com/akitaonrails/ComfyUI-Docker-CUDA-preloaded.git
cd ComfyUI-Docker-CUDA-preloaded
docker compose build

Since it’s more complex, this time I had to put together a Docker Compose. So to bring it up, after the build finishes, just do this:

docker compose up

Now it’s going to take a while, because by default it will download almost 500GB of pre-trained models so it can do almost anything image-related. Yes, to play with A.I. locally you need infrastructure. Otherwise, rent a beefy machine with lots of storage on a RunPod or similar and run it remotely. You can download fewer models, I’ll explain that next.

On Docker Compose. I recommend avoiding the “-d” option to bring it up as a daemon, because it’s good to reserve a terminal to keep watching the outputs (you can run docker compose logs --follow if you want, but it’s easier directly).

ComfyUI is a more complex program than average, much more so than something like FramePack. It supports installing “extensions” (plugins, addons, call them what you want). And honestly on its own it doesn’t do much, you need to install several extensions for it to start being really useful. Every now and then one of these extensions doesn’t handle errors properly and blows up in the console, something like this:

It’s always useful to keep an eye on the console to find out if it tried to load a file that doesn’t exist. Then you can grab the file name and search Google, download it and put it in the right place. Or if it’s a really buggy extension that’s better off removed from the “custom_nodes” directory, and so on. Without watching the console, it doesn’t show up in the web interface and you’ll be left in the dark.

A lot of the models and extensions I based on the Ultimate ComfyUI version 3 configuration recommended by Aitrepreneur, again. Watch this video of his to get all the details and everything that’s possible to do. He has the scripts for Linux, Windows, and the workflows in his paid Patreon version and, of course, I won’t share the workflows because they’re not mine. In theory, my config should be able to do what he teaches.

Aitrepreneur’s V3 workflow is really badass. But I can’t share it because it’s closed material on his Patreon, but here’s a screenshot of my ComfyUI with all of his stuff loaded:

But the config itself, I redid it entirely to work in this Docker. You can load any other open workflow you find on a Reddit or wherever.

Here’s what I did:

Models

In the project there has to be a “models” directory, if there isn’t one, create it, because docker compose will map it inside the container. When it starts, it’ll run the file init_models.sh. This script will load a configuration file you can edit later: models.conf. It’s huge and a piece of it looks like this:

...
[CONTROLNET]
https://huggingface.co/XLabs-AI/flux-controlnet-collections/resolve/main/flux-canny-controlnet-v3.safetensors
https://huggingface.co/XLabs-AI/flux-controlnet-collections/resolve/main/flux-depth-controlnet-v3.safetensors
https://huggingface.co/brad-twinkl/controlnet-union-sdxl-1.0-promax/resolve/main/diffusion_pytorch_model.safetensors|controlnet-union-sdxl-1.0-promax.safetensors
https://huggingface.co/lllyasviel/ControlNet-v1-1/resolve/main/control_v11p_sd15_canny.pth
https://huggingface.co/lllyasviel/ControlNet-v1-1/resolve/main/control_v11f1p_sd15_depth.pth
https://huggingface.co/lllyasviel/ControlNet-v1-1/resolve/main/control_v11p_sd15_openpose.pth
https://huggingface.co/Aitrepreneur/FLX/resolve/main/Shakker-LabsFLUX1-dev-ControlNet-Union-Pro.safetensors

[STYLE_MODELS]
https://huggingface.co/Aitrepreneur/FLX/resolve/main/flux1-redux-dev.safetensors

[SAMS]
https://huggingface.co/Aitrepreneur/FLX/resolve/main/sam_vit_b_01ec64.pth

Each section maps to a sub-directory, so “[SAMS]” will map to “models/sams” and download the binaries to the right places. There are some special ones in the “[GIT_REPOS]” section, for those that can be cloned via git, or “[CUSTOM]” for files you need to download later inside those cloned projects, for example. I don’t yet know if it can be simplified, but I picked this up from Aitrepreneur’s config.

The ideal is to always keep this list organized with models you find later. If you want to contribute, that would also be cool. The reason is that everything is scattered across all kinds of sites out there, you download manually, then move to the directory inside “models”. Tomorrow, if you reinstall your machine, how are you supposed to remember all the sites? There are dozens of available models.

In the next post I’ll try to summarize what the hell “checkpoints”, “diffusion models”, “loras”, “controlnet” and all the rest are. But for now, the file extension doesn’t say much. “.pt” for example only means it’s a file PyTorch can open, but it doesn’t tell you whether it’s a clip or a text encoder, for example. Same thing with “.safetensors”, it can be anything, and ComfyUI needs each file to be in the correct sub-directory in order to use it, you can’t just go around moving files randomly.

The “init_models.sh” script runs every time Docker is restarted and is smart enough to only download URLs that aren’t already downloaded in the “models” directory. That’s why it always runs when the container comes up, in the entrypoint. That’s one of the advantages of my config: it has automatic maintenance.

Extensions and Dependencies

I made a second script called init_extensions.sh, which also runs at the container’s entrypoint and which you shouldn’t touch, but it loads another configuration file called extensions.conf and that one, yes, you can mess with and add new extensions later. A piece of it looks like this:

[EXTENSIONS]
https://github.com/ltdrdata/ComfyUI-Manager.git
https://codeberg.org/Gourieff/comfyui-reactor-node.git
https://github.com/ssitu/ComfyUI_UltimateSDUpscale.git
https://github.com/kijai/ComfyUI-LivePortraitKJ.git
https://github.com/PowerHouseMan/ComfyUI-AdvancedLivePortrait.git
...

Here I declare all the extensions that add new functionality on top of ComfyUI, in particular new NODES, which is why they live in the “custom_nodes” directory, which is a volume external to Docker and therefore persistent, meaning every new extension survives container restarts.

But there’s still a BIG catch: Python Dependencies. A nightmare.

The Docker image build does a bunch of pip install and since I’m using Virtual ENV, everything gets installed in /venv inside the container, as it should.

However, the extensions that get installed outside the build - every time the container restarts - tend to be Python code and also have more dependencies. Extensions are GitHub projects and may be changing right this minute. If they change and you do a git pull to update, you need to run pip install -r requirements.txt. But if you have dozens of extensions, running pip install for each one on every Docker restart takes a long time to do almost nothing. As I said, a nightmare.

My solution - to brag a bit - fixes a good chunk of this maintenance. When the init_extensions.sh script runs, if an extension from the list is already installed, it’ll skip it. Then it’ll write to the ./custom_nodes/.last_commit/*.commit directory the latest commit of each extension. When Docker restarts, it’ll do a git fetch and check whether the latest commit hash has changed.

Only if it has changed will it run pip install for that extension that got an update, and skip all the others that haven’t changed since the last restart, saving A LOT of time and avoiding having to manually update things. Since I’m using VENV, everything will stay persisted in the “/venv” volume. Yes, it’s a VOLUME, because it changes after the build with each extension update.

This way, everything in the image gets copied into that volume, and everything the extensions install on the side also goes into that volume. Every time you restart, it all comes back the way it was. That was the solution I found and so far it seems to work just fine.

But it’s only a matter of time until some poorly made extension installs dependencies that break other dependencies, or an actual case I went through: there was an extension that crashes with no error message if you’re using Python 3.11, the Zoe Depth Map from the comfyui_controlnet_aux extension, one of the packages that seems to be popular.

I hadn’t realized I’d started using a Docker base image of ubuntu22 instead of ubuntu24, I was afraid of using something too new and breaking things, but I ended up using something too old and it broke just the same. Managing versioning is a pain. Anyway, I changed the Dockerfile to ubuntu24.

But in the external VENV volume now there were a bunch of dependencies pinned to Python 3.11. No problem, just delete the volume:

docker compose down # make sure it's stopped
docker volume rm comfyui-venv
rm ./custom_nodes/.last_commits/*.commit

And done, the VENV will start over empty, fill up with the correct Python 3.12 dependencies from the image, and when the container starts my init_extensions.sh script won’t find “.last_commits” and will force a pip install -r requirements.txt of all the extensions, now with Python 3.12. Super clean and reliable.

If even so you get an error, then it might be a bug in a specific extension, just go to its directory in “./custom_nodes” and delete it manually before restarting the container.

I think that’s the least complicated thing you can do in this case. This docker wasn’t built to run on its own on a server, it’s meant to run on your own local machine, where you’re monitoring the terminal output anyway.

Oh yes, if a new version of ComfyUI comes out then you have to rebuild the image and delete the VENV volume. The image is static, don’t forget. Inside, the Dockerfile does a new git clone and grabs the newest commit. Then it’ll install newer python packages, so you need to wipe the VENV volume and have the extensions reinstall their dependencies afterwards too. It’s a huge pain, but that’s just how it works.

Conclusion

With all that done, with a simple docker compose up I can have a stable ComfyUI environment isolated from the rest of my system, without dirtying anything with thousands of dubious dependencies. When I’m done I just do docker compose down or “ctrl-c” in its console and that’s it, my system stays clean.

On top of that, directories like “models” and their 500GB of models stay separate, you can back them up elsewhere if you need to. And if you want to bring it up on another machine, just take only those directories and bring up Docker Compose there and it has to come up exactly the same way, zero-setup. That was my goal in Dockerizing ComfyUI, FramePack, Video2K: to have everything portable, isolated and clean to bring up on any machine later without having to run sketchy installation scripts directly on my machine.

On my X I already showed my ComfyUI working. I loaded some random workflow I found on the Web and look at this:

In this workflow I upload a reference image and I can write a prompt for how I want to transform it:

With ComfyUI I have control over every step of the process, for example, this workflow can separate things like Depth Map and Edge Contour from the original image, to use as context before making the final image, ensuring a much more precise result:

And here’s a result I already got using the “waiNSFIllustrious” model that this workflow suggests, which is a model trained to generate anime-style images (there are dozens, for various different styles).

Switching the model to Mistoon, based on Stable Diffusion (SDXL), here’s another result, with the same prompt, in the same workflow:

And I can keep tuning dozens of parameters inside this workflow, swap vaes, text encoders, controlnets and much more until I get exactly the result I want. That’s the power of ComfyUI and its Custom Nodes and Workflows. That’s what I’ll try to explain the basics of in the next post.

I went poking around GitHub and there is an Awesome Image Colorization page with a bunch of research papers. Very useful for researchers but totally useless for me, since I am not going to build one from scratch lol. There were links to projects like ChromaGAN, but that one has been discontinued for about 5 years. And several other projects I saw were also discontinued ages ago. I do not know why there is so little open source still actively maintained.

Luckily I bumped into a promising one: DDColor.

Let’s clone the repo. And to keep going, I prefer to do everything inside Docker. Downloading Python dependencies always messes up my system and leaves a bunch of garbage behind, so the best thing is to isolate it all. Another thing, you need to download the binaries of the pre-trained models. Just for that I will use a bit of Python because of the “modelscope” lib that handles it:

git clone https://github.com/piddnad/DDColor.git
cd DDColor

mkdir modelscope

# create a new venv inside the DDColor project
python -m venv venv

venv/bin/pip3 install modelscope

venv/bin/python3 -c "from modelscope.hub.snapshot_download import snapshot_download; snapshot_download('damo/cv_ddcolor_image-colorization', cache_dir='./modelscope')"

Good Python practice is to do everything inside a VENV, right? Anyway, this should download the model binary, which weighs almost 900MB. Not huge.

Now we need a Dockerfile:

# Use NVIDIA CUDA base image with cuDNN 8 and Python support
FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu22.04

# Install Python and system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    python3 python3-pip git libgl1 libglib2.0-0 && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

# Set working directory
WORKDIR /app

# Copy DDColor source code into the image
COPY . /app

# Install PyTorch (CUDA 11.8 compatible) and matching torchvision/torchaudio
RUN pip3 install torch==2.2.0 torchvision==0.17.0 torchaudio==2.2.0 \
    --index-url https://download.pytorch.org/whl/cu118

# Install Python dependencies, skipping dlib (not needed for inference)
RUN sed '/dlib/d' requirements.txt > temp-req.txt && pip3 install -r temp-req.txt && rm temp-req.txt

# Optional: install modelscope if you want to run snapshot_download manually inside the container
RUN pip3 install modelscope

Too lazy to open a pull request for this, if anyone wants to, send it over there.

Now we need to put a black and white image somewhere:

mkdir input
mkdir results
mv ~/Downloads/bw.jpg input/

Since my girlfriend’s photos are family and private, obviously I am not going to share them, so I grabbed a random one from Google Images:

Now we drop it in “./input” and run Docker with this command:

docker run --rm --gpus all \
  -v "$PWD/input":/workspace/input_images:ro \
  -v "$PWD/results":/workspace/results:rw \
  -v "$PWD/modelscope":/app/modelscope:ro \
  ddcolor:latest \
  python3 infer.py \
    --model_path /app/modelscope/damo/cv_ddcolor_image-colorization/pytorch_model.pt \
    --input /workspace/input_images \
    --output /workspace/results

Pay attention to the directory mapping. And note the “–gpus” option, which only works in my case because I have an RTX 4090 installed here. I have no idea if it is the same with AMD, but since the image is based on cuDNN/CUDA, I would say no. Ask ChatGPT.

If everything is right and it runs successfully, it will take just 1 second and produce this output in the terminal:

==========
== CUDA ==
==========

CUDA Version 11.8.0

Container image Copyright (c) 2016-2023, NVIDIA CORPORATION & AFFILIATES. All rights reserved.

This container image and its contents are governed by the NVIDIA Deep Learning Container License.
By pulling and using the container, you accept the terms and conditions of this license:
https://developer.nvidia.com/ngc/nvidia-deep-learning-container-license

A copy of this license is made available in this container at /NGC-DL-CONTAINER-LICENSE for your convenience.

Output path: /workspace/results
100%|██████████| 1/1 [00:00<00:00,  4.09it/s]

And here is the result that shows up in the ./results directory:

Yes, I was impressed. Even with the image being from the Web, with watermark and all, it did everything properly and worked!!

The only problem left is being able to use a reference image to try to pull the colors. That is a harder problem and I asked ChatGPT, which answered me this:

No native support for a reference image:

The DDColor model, both in the official version hosted on ModelScope and in the piddnad/DDColor GitHub repo, was designed only for automatic colorization of black and white images, with no option to accept a reference image as input. The official description itself makes it clear that the model takes a single B&W image and returns a colored image.

The model’s forward method expects only one tensor, the B&W image converted into artificial RGB (actually the luminance expanded into 3 channels). In other words, there is no place in the model to pass a second image as a color reference.

This is also evident in the original predict.py from the Cog library, which only accepts the image parameter as input — with no support for reference, ref_image or anything of the kind.

How to solve the problem: two possible approaches

Since DDColor does not natively support a reference image to guide the colors, we have two alternatives:

🔁 1. Use a model specialized in reference-based colorization

There are models developed specifically for this, such as:

• Deep Exemplar-based Colorization (Zhang et al., CVPR 2018)

• ChromaGAN (2019)

• Exemplar-Transformer Colorization (Yin et al., ACM MM 2021)

• UniColor (Huang et al., 2022)

These models accept two images:

• The B&W image (main input)

• A colored image as a color reference

These models map semantic similarities (e.g., “skin here should have the same skin color as over there”) and do a transfer based on the image content, getting much more detailed and specific results. However, this would require:

• Downloading different weights

• Completely changing the architecture used

• Adapting the pipeline and inference

🎯 2. Use global color transfer after the DDColor output (our current approach)

The practical and lightweight solution we used was: ➡️ Run DDColor normally to generate the colored image automatically ➡️ Then globally adjust the colors of the result to look more like the reference image.

This adjustment is done with the Reinhard et al. (2001) algorithm:

1. We convert both the output image and the reference to the Lab color space.

2. We compute the mean and standard deviation of the a and b channels (the ones that represent color).

3. We adjust the result to have the same statistical distribution of color as the reference image.

4. This tends to leave the image with the same overall “mood” or tone (warmer, cooler, more vibrant).

This method is fast, lightweight, and works without altering the DDColor model.

Continuing

I used the modification it suggested to the predict.py file:

import os
import cv2
import numpy as np
import torch
import torch.nn.functional as F
from cog import BasePredictor, Input, Path
from basicsr.archs.ddcolor_arch import DDColor

def color_transfer(reference_bgr: np.ndarray, target_bgr: np.ndarray) -> np.ndarray:
    """Transfer color palette of reference image to target image using Lab mean/std."""
    # Convert BGR images to Lab color space (float32 for precision)
    ref_lab = cv2.cvtColor(reference_bgr, cv2.COLOR_BGR2LAB).astype("float32")
    tgt_lab = cv2.cvtColor(target_bgr, cv2.COLOR_BGR2LAB).astype("float32")
    # Split channels
    L_ref, a_ref, b_ref = cv2.split(ref_lab)
    L_tgt, a_tgt, b_tgt = cv2.split(tgt_lab)
    # Compute mean and std for reference and target (a and b channels)
    a_ref_mean, a_ref_std = a_ref.mean(), a_ref.std()
    b_ref_mean, b_ref_std = b_ref.mean(), b_ref.std()
    a_tgt_mean, a_tgt_std = a_tgt.mean(), a_tgt.std()
    b_tgt_mean, b_tgt_std = b_tgt.mean(), b_tgt.std()
    # Subtract target means, scale by reference/target std, add reference means
    # (Avoid division by zero in case of zero std)
    if a_tgt_std > 1e-6:
        a_tgt = ((a_tgt - a_tgt_mean) * (a_ref_std / a_tgt_std)) + a_ref_mean
    else:
        a_tgt = a_tgt - a_tgt_mean + a_ref_mean
    if b_tgt_std > 1e-6:
        b_tgt = ((b_tgt - b_tgt_mean) * (b_ref_std / b_tgt_std)) + b_ref_mean
    else:
        b_tgt = b_tgt - b_tgt_mean + b_ref_mean
    # Clip values to valid Lab range [0,255] after transfer
    a_tgt = np.clip(a_tgt, 0, 255)
    b_tgt = np.clip(b_tgt, 0, 255)
    # Merge channels back (use original L from target to preserve brightness)
    merged_lab = cv2.merge([L_tgt, a_tgt, b_tgt]).astype("uint8")
    # Convert back to BGR color space
    result_bgr = cv2.cvtColor(merged_lab, cv2.COLOR_LAB2BGR)
    return result_bgr

class ImageColorizationPipeline:
    """Helper pipeline to load DDColor model and process images."""
    def __init__(self, model_path: str, input_size: int = 256, model_size: str = "large"):
        self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
        # Choose encoder backbone based on model size
        encoder_name = "convnext-t" if model_size == "tiny" else "convnext-l"
        # Initialize DDColor model
        self.model = DDColor(
            encoder_name=encoder_name,
            decoder_name="MultiScaleColorDecoder",
            input_size=[input_size, input_size],
            num_output_channels=2,    # model predicts ab channels
            last_norm="Spectral",
            do_normalize=False,
            num_queries=100,
            num_scales=3,
            dec_layers=9,
        ).to(self.device)
        # Load weights
        state = torch.load(model_path, map_location="cpu")
        # Some checkpoints store weights under 'params' key
        self.model.load_state_dict(state.get("params", state), strict=False)
        self.model.eval()
        self.input_size = input_size  # store for processing

    @torch.no_grad()
    def process(self, img_bgr: np.ndarray) -> np.ndarray:
        """Colorize a BGR image (numpy array) using the loaded DDColor model."""
        # Preserve original resolution L channel
        orig_h, orig_w = img_bgr.shape[:2]
        # Convert to Lab and extract L channel at original size
        img_lab = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2LAB).astype("float32")
        orig_L = img_lab[:, :, 0:1]  # shape (H, W, 1)
        # Prepare grayscale input at model resolution
        # Resize input to model expected size
        inp = cv2.resize(img_bgr, (self.input_size, self.input_size))
        inp_lab = cv2.cvtColor(inp, cv2.COLOR_BGR2LAB).astype("float32")
        L = inp_lab[:, :, 0:1]
        # Create grayscale Lab image by zeroing AB channels
        gray_lab = np.concatenate([L, np.zeros_like(L), np.zeros_like(L)], axis=2)
        # Convert back to RGB (now it's a gray RGB image of size input_size)
        gray_rgb = cv2.cvtColor(gray_lab.astype("uint8"), cv2.COLOR_LAB2RGB)
        # Prepare tensor and run model
        tensor = torch.from_numpy(gray_rgb.transpose(2, 0, 1)).float().unsqueeze(0).to(self.device)
        out_ab = self.model(tensor)  # output is (1,2,H_out,W_out) in Lab AB
        out_ab = out_ab.cpu().float()
        # Resize output AB to original image size
        out_ab_resized = F.interpolate(out_ab, size=(orig_h, orig_w), mode="bilinear", align_corners=False)
        out_ab_resized = out_ab_resized[0].numpy().transpose(1, 2, 0)  # (H, W, 2)
        # Combine original L and predicted AB, then convert to BGR
        out_lab = np.concatenate([orig_L, out_ab_resized], axis=2).astype("uint8")
        out_bgr = cv2.cvtColor(out_lab, cv2.COLOR_LAB2BGR)
        return out_bgr

class Predictor(BasePredictor):
    def setup(self):
        """Load models into memory for efficient multiple predictions."""
        # Determine paths for large and tiny model weights
        large_model_path = "checkpoints/ddcolor_modelscope.pth"
        tiny_model_path  = "checkpoints/ddcolor_paper_tiny.pth"
        # (Ensure the above files exist. If not, download from ModelScope or HuggingFace as described.)
        # Initialize pipelines for large and tiny models
        self.colorizer_large = ImageColorizationPipeline(model_path=large_model_path, input_size=512, model_size="large")
        self.colorizer_tiny  = ImageColorizationPipeline(model_path=tiny_model_path,  input_size=512, model_size="tiny")

    def predict(
        self,
        image: Path = Input(description="Grayscale input image."),
        reference: Path = Input(description="Optional reference image to guide colors", default=None),
        model_size: str = Input(description="Model size to use (large = highest quality, tiny = faster).",
                                choices=["large", "tiny"], default="large"),
    ) -> Path:
        """Run a single prediction. Colorizes the image, optionally using a reference image for color bias."""
        # Read input image
        img = cv2.imread(str(image))
        if img is None:
            raise ValueError("Failed to load input image")
        # Select model pipeline
        pipeline = self.colorizer_tiny if model_size == "tiny" else self.colorizer_large
        # Colorize the image using DDColor
        output_bgr = pipeline.process(img)
        # If a reference image is provided, transfer its color style to the output
        if reference is not None:
            ref_img = cv2.imread(str(reference))
            if ref_img is None:
                raise ValueError("Failed to load reference image")
            # Only apply transfer if reference is a color image
            if ref_img.shape[2] == 3:
                output_bgr = color_transfer(ref_img, output_bgr)
        # Save result
        out_path = "/tmp/out.png"
        cv2.imwrite(out_path, output_bgr)
        return Path(out_path)

With this modification I can run with a new parameter, note the “–ref” option that exists now and place your image in the right spot:

❯ docker run --rm --gpus all \
  -v "$PWD/input":/workspace/input_images:ro \
  -v "$PWD/results":/workspace/results:rw \
  -v "$PWD/ref_images":/workspace/ref_images:ro \
  -v "$PWD/modelscope":/app/modelscope:ro \
  -v "$PWD/infer.py":/app/infer.py:ro \
  ddcolor:latest \
  python3 /app/infer.py \
    --model_path /app/modelscope/damo/cv_ddcolor_image-colorization/pytorch_model.pt \
    --input /workspace/input_images \
    --ref /workspace/ref_images/images.jpg \
    --output /workspace/results

I passed in another colored reference photo but saw no difference in the result. Once again, I asked ChatGPT:

Why didn’t you notice a difference in the result?

The global color transfer only changes the “overall palette” — and not the colors of each object.

If the reference image has soft tones similar to what DDColor would already apply automatically, the final effect will look identical.

But if you use as reference a heavily saturated image (for example, an orange sky, or a deep blue environment), you will see DDColor’s output visually pulled toward that style.

Conclusion

I followed the suggestion and downloaded another totally unrelated image, colored, super saturated with vibrant colors to see if it made a difference. This is the reference image I passed to Docker:

And here is the new result applying it to the previous image in post-processing (this step is no longer A.I., it really is just image post-processing).

Compare it with the other re-colorized photo, I will put it down here again so you can compare:

Got it? Now you have to keep testing with different references to see how they influence the final result, but indeed, it manages to apply the Reinhard algorithm and do a global color transfer. As the name says, it is “global”, not “per object”, so it is hard to control only parts of the image — it acts on the whole image. But in theory I think you could do a manual colorization in Photoshop with saturated colors, near where you want to influence, to try to nudge it, but I have not tried that yet. Later, if anyone does, drop it in the comments.

But that is it. Now at least I can have fun grabbing old family photos and re-colorizing them.

But WebKit is known for being very complicated to deal with. So I can only imagine the nightmare to maintain PhantomJS, which is akin to maintaining a full-blown web browser like Chrome or Safari.

So it’s no wonder that when the Chrome team announced the availability of the Chrome Driver, then the maintainer of PhantomJS decided to step down.

If you know the contributors of PhantomJS, say thank you, as it helped us build more solid user features.

That being said, fear not. You can easily replace Poltergeist/PhantomJS with Selenium WebDriver/Chrome Driver in your RSpec/Capybara setup.

My friend Lucas Caton wrote about it in June this year. Follow his blog as well.

If you’re using Linux with the Chromium browser, you don’t need to install anything, as the Chrome Driver comes with Chromium. Otherwise, you need to install the proper packages for your operating system. For example, brew install chromedriver for OS X or pacaur -S chromedriver on Arch if you don’t like to have Chromium around. You may need to tweak your PATH on Ubuntu though.

Rule of thumb: install Chromium.

In my case, this is what had to change:

# Gemfile
- gem "poltergeist"
+ gem "selenium-webdriver"
+ gem "rspec-retry"

Then in the Capybara setup:

Capybara.server = :puma # Until your setup is working
Capybara.server = :puma, { Silent: true } # To clean up your test output

- Capybara.register_driver :poltergeist do |app|
-   options = {
-     timeout: 3.minutes,
-     phantomjs_options: [
-       '--proxy-type=none',
-       '--load-images=no',
-       '--ignore-ssl-errors=yes',
-       '--ssl-protocol=any',
-       '--web-security=false'
-     ]
-   }
-   Capybara::Poltergeist::Driver.new(app, options)
- end
- Capybara.javascript_driver = :poltergeist

+ Capybara.register_driver :chrome do |app|
+   capabilities = Selenium::WebDriver::Remote::Capabilities.chrome(
+     chromeOptions: {
+       args: %w[ no-sandbox headless disable-popup-blocking disable-gpu window-size=1280,1024]
+     }
+   )
+ 
+   Capybara::Selenium::Driver.new(app, browser: :chrome, desired_capabilities: capabilities)
+ end
+ 
+ Capybara::Screenshot.register_driver :chrome do |driver, path|
+   driver.save_screenshot(path)
+ end
+ 
+ Capybara.javascript_driver = :chrome

Capybara.default_max_wait_time = 5 # you may want to increase this timeout if your app is heavy to load

In feature specs, sometimes Rails itself takes a long while to load up, compile assets, etc., and the first feature spec may time out. To avoid a failure in the test run, it’s recommended to add the rspec-retry gem, as I did above, and add the following to your spec/rails_helper.rb:

require 'rspec/retry'

RSpec.configure do |config|
  ...
  # show retry status in spec process
  config.verbose_retry = true
  # Try twice (retry once)
  config.default_retry_count = 2
  # Only retry when Selenium raises Net::ReadTimeout
  config.exceptions_to_retry = [Net::ReadTimeout]
  ...
end

And that should be it. I didn’t have to touch any of my feature specs and they all ran beautifully. So kudos to the respective teams that maintain Capybara, Selenium-WebDriver for supporting this.

If you’re a Node.js developer as well, you probably used something like Casper, which is said to support Chrome Headless as well. But while we’re at it, you should check out Puppeteer as well, from the Google team itself. It is a promise-based library where you can code like this:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({path: 'example.png'});

  await browser.close();
})();

So yeah, Chrome Headless seems like a very good option as most users actually use the Chrome browser, so it means we should have more reliable feature specs and also web crawling tools.

For each application you create, it even offers you separate development, staging, and production environments, with separate key/secret tokens.

One problem I stumbled upon these days is that I was quickly zeroing out the free development environment message quota (200,000 messages a day). That’s because all my team was using the same key and also the Continuous Integration server was doing live connections whenever it ran in the same environment. That can quickly consume all the quota you have and block both your development and CI.

It’s actually not a good practice to do live connections to external systems in testing situations. The tests can fail randomly for a number of reasons, so we should always mock those. But mocking a complex system (WebSockets and HTTP) like Pusher is not trivial.

Fortunately, I found this Pusher Fake. It basically implements all the necessary APIs and WebSocket endpoints to mimic Pusher and fool both server and js/client to communicate with it.

The idea is for your Rails app, in development mode, to fork a separate server process for the Pusher client to connect to. This gem is both a simple Pusher-clone server and a series of wrappers to load it up in your setup.

First things first.

In your application, you will have both a Ruby side Pusher client connection setup to push messages to a channel in the Pusher server. And a Javascript, client-side, Pusher instance mainly to subscribe to a channel in a WebSocket connection and receive messages.

First we need to set up the Ruby side. Usually it’s in a config/initializers/pusher.rb configuration like this:

Pusher.app_id = ENV['PUSHER_APP']
Pusher.key    = ENV['PUSHER_KEY']
Pusher.secret = ENV['PUSHER_SECRET']
Pusher.cluster = ENV['PUSHER_CLUSTER']
# never set Pusher.host or Pusher.port

Notice that I am using environment variables to hold the configuration. You should use something like the figaro gem or the dotenv-rails gem. For example:

PUSHER_APP: "xpto"
PUSHER_KEY: "abcd1234"
PUSHER_SECRET: "abcd1234"
PUSHER_CLUSTER: "us2"

At the very least you must have an application ID, a key, a secret, and a cluster name. All of these are provided by Pusher whenever you register a new application there.

Second, we need to set up the Javascript instance. Usually, you have something in the assets/javascripts directory like this:

// .js.erb example
window.pusher = new Pusher(<%= ENV['PUSHER_APP] %>, {
  cluster: <%= ENV['PUSHER_KEY'] %>,
  encrypted: <%= ENV['PUSHER_ENCRYPTED'] %>})

In a Chrome Development Console, you can inspect this instance by typing:

Pusher.instances[0]

This way you can make sure it’s picking up the correct configurations for the connection and also debug problems.

The dependencies are the pusher gem in your Gemfile and the javascript client.

# Gemfile
gem 'pusher'

In the case of the javascript file you can either add it to your project and rely on Webpacker:

yarn add pusher

Then, in your ES6 javascript file, you can do:

const Pusher = require('pusher-js');

Or you can link it directly in your layout:

<script src="https://js.pusher.com/4.2/pusher.min.js"></script>

For more information on the Pusher-js client, read its README file.

Adding Pusher Fake

At this point, you should be able to connect to the real Pusher account and see the real-time magic happening.

You’re also already consuming the free quota you have available in your development environment on Pusher. For most people, this should suffice.

But we want to NOT connect to Pusher over the internet and keep everything local for development and testing. Let’s start by adding the Pusher Fake to our Gemfile:

group :development, :test do
  gem 'pusher-fake'
end

Now, this is where the Pusher Fake setup can get convoluted if you don’t understand what’s happening. As I said before, PusherFake must fork a new process to load a local server that mimics Pusher.

To load it up you must point to the local server. Remember our config/initializers/pusher.rb ? We just need to require a simple file like this:

Pusher.app_id = ENV['PUSHER_APP']
Pusher.key    = ENV['PUSHER_KEY']
Pusher.secret = ENV['PUSHER_SECRET']
Pusher.cluster = ENV['PUSHER_CLUSTER']

if Rails.env.development?
  require "pusher-fake/support/base"
end

This alone presents a LOT of problems if you’re not careful. This require will fork a new process. If you’re using a single-process web server like Webrick or Thin, you should be ok. If you’re using Puma, Unicorn, or Passenger with a maximum of just one process, you should also be good. But if you load a web server that itself forks new processes, you will have trouble.

In practice, I’d rather load the Pusher Fake server separately, in stand-alone mode. Fortunately it provides a command line command to start it up. And it’s good practice to set that up in a Procfile.dev file and use foreman to start everything for you. The Procfile.dev looks like this:

web: bundle exec rails s -p 3000
db: postgres -D /usr/local/var/postgres
redis: redis-server /usr/local/etc/redis.conf
mailcatcher: mailcatcher -f
pusherfake: pusher-fake -i ${PUSHER_APP:-xpto} --socket-host 0.0.0.0 --socket-port ${PUSHER_WS_PORT:-45449} --web-host 0.0.0.0 --web-port ${PUSHER_PORT:-8888} -k ${PUSHER_KEY:-abcd1234} -s ${PUSHER_SECRET:-abcd1234}

As a bonus, look how I configure other services such as PostgreSQL, Redis, etc.

If you didn’t know, you can use ${VARIABLE_NAME:-default_value} to use an environment variable or have a default value in case the variable doesn’t exist. This means that your environment variable configured with Figaro or Dotenv must have the same values.

PUSHER_APP: "xpto"
PUSHER_KEY: "abcd1234"
PUSHER_SECRET: "abcd1234"
PUSHER_CLUSTER: "us2"
PUSHER_HOST: "127.0.0.1"
PUSHER_PORT: "8888"
PUSHER_WS_HOST: "127.0.0.1"
PUSHER_WS_PORT: "45449"

Now your config/initializers/pusher.rb should be something like this:

Pusher.app_id = ENV['PUSHER_APP']
Pusher.key    = ENV['PUSHER_KEY']
Pusher.secret = ENV['PUSHER_SECRET']
Pusher.cluster = ENV['PUSHER_CLUSTER']

if Rails.env.development?
  Pusher.host = ENV['PUSHER_HOST']
  Pusher.port = ENV['PUSHER_PORT']
end

And Pusher-js config somewhere in your app/assets/javascripts/ directory will resemble something like this:

<% if defined?(PusherFake) %>
    <% if Rails.env.test? %>
    var pusher = <%= PusherFake.javascript(cluster: ENV["PUSHER_CLUSTER"]) %>
    <% else %>
    window.pusher = new Pusher(<%= ENV['PUSHER_KEY'] %>, {
      cluster: <%= ENV['PUSHER_CLUSTER'] %>,
      wsHost: <%= ENV['PUSHER_WS_HOST'] %>,
      wsPort: <%= ENV['PUSHER_WS_PORT'] %>,
      encrypted: <%= ENV['PUSHER_ENCRYPTED'] %>})    
    <% end %>
<% else %>
    window.pusher = new Pusher(<%= ENV['PUSHER_KEY'] %>, {
      cluster: <%= ENV['PUSHER_CLUSTER'] %>,
      encrypted: <%= ENV['PUSHER_ENCRYPTED'] %>})
<% end %>

Remember that this is a Javascript+ERB file, so we can fetch the same environment variables for the configuration.

Now, whenever you foreman start -f Procfile.dev -p 3000 it will load the Pusher Fake server with the proper development configurations and both your ruby server-side and javascript client-side should connect to it without any problems.

Also, notice the if Rails.env.test? bit. This is for your RSpec test suite. In the case of the testing environment, we won’t load the fake server manually, instead, we will create something like spec/support/pusher-fake.rb with:

require "pusher-fake/support/rspec"

And that’s it. The PusherFake.javascript will define default WebSocket connection configuration and the require above will both fork the fake server and set Rspec to clean the channels on each test run (through PusherFake::Channel.reset).

This way your testing environment will also avoid connecting to the external, real, Pusher server.

The key to all this is the environment variables. You must make sure that every piece is loading the same configuration, otherwise you will have the fake server binding to a different port than the Pusher-js is connecting to, and you will have errors. Debug with care.

Most importantly: if you did it all correctly, you are now independent of the real Pusher server for development and testing environments, you won’t ever reach any quota limits, and your team and your CI will be able to work uninterruptedly, with a deterministic behavior.

Anyway, the website itself is super simple. A single page site. I chose to use Rails 5.1 as the site structure because it takes care of all the stuff I’d have to add manually in any other framework. Especially now that it brings native Yarn and Webpack support it’s a breeze to use by any competent front-end developer.

But even with the many built-in niceties, a full production setup still requires extra steps that most beginners will not know. So I decided to compile a small checklist of things you must take care of before deploying to production. It’s not an extensive and complete list for all use cases, but this should be enough for most small cases.

• Setting up the project
• Adding a CDN and configuring CORS support (to be able to load fonts for example)
• Adding Memcached

Setting up the project

One thing that most people forget, even experienced developers, is that the rails new command used to bootstrap the initial project structure accepts many option flags. Instead of having to manually tweak files later, you can start like this:

rails new your_project \
--database=postgresql \
--webpack=react \
--skip-action-cable \
--skip-coffee
--skip-turbolinks

If you’re building with React or another full-featured javascript framework, you will probably want to skip Turbolinks. Otherwise, if it’s a simple site, do use Turbolinks.

Start using PostgreSQL from the get-go, don’t use Sqlite3.

Skip Action Cable. Prefer a real solution such as Pusher.com. If you really need something done in-house, consider something like my solution with Elixir, the Ex Pusher Lite. Take this recommendation with a grain of salt, of course, for small things Action Cable is more than enough. I may write another post just elaborating on this point if people indicate they want to in the comments section.

Anyway, I digress. Make sure you have 2 boot files, first the canonical Procfile to be used by Heroku in production:

web: bin/rails server -p $PORT -b 0.0.0.0

Second, a Procfile.dev to be used only in your development environment:

web: ./bin/rails server
webpacker: ./bin/webpack-dev-server

This is how you fire up the webpack server that will compile your assets in real-time during development. You need to also remember to run these two dependency commands now:

yarn install
bundle install

Install javascript dependencies with yarn add [package] and that’s it! In production you don’t use the webpack server (which is why we don’t add it to the production Procfile), instead Heroku automatically detects the webpacker gem then it installs the nodejs buildpack, runs yarn install for you and when rails assets:precompile runs it will also execute yarn run which will pre-compile all the assets (javascript, stylesheets, images) with the proper fingerprinting for cache busting and everything else we are used to in the normal Rails Asset Pipeline.

So, for Heroku, you basically don’t have to do anything. And in a custom deployment server you just need to remember to run the assets:precompile task and have it do everything for you.

Adding a CDN and configuring CORS

This is really super easy. There is no reason why anyone wouldn’t add a CDN to any website. Please just do it.

Open your AWS Management Console and open CloudFront. From there click on “Create Distribution” and just follow the defaults in the Wizard. The requirement is that you MUST know the domain and sub-domain you want to point to (for example “www.theconf.club”) in the “Origin Domain Name” field.

The only customization you MUST do is to change the “Forward Headers” option to “Whitelist” in the “Default Cache Behavior Settings”. Then you need to add “Origin”, “Access-Control-Request-Headers”, and “Access-Control-Request-Method” to the Whitelist. And that’s it, now your distribution is CORS enabled.

It will take some time to create (it has to configure many data centers around the world), but you will end up with a URL representing your distribution, something like doz7rtw2u3wg4.cloudfront.net. I recommend you add it as a Heroku environment variable like this:

heroku config:set CDN_URL=doz7rtw2u3wg4.cloudfront.net

Now, edit your config/environments/production.rb and add the following:

config.action_controller.asset_host = ENV['CDN_URL'] if ENV['CDN_URL']

To actually use the CDN you must declare every asset you use across your view templates using Rails View Helpers such as image_tag, asset_path, javascript_pack_tag, stylesheet_pack_tag, stylesheet_link_tag, etc. The Rails bootstrap already creates layout templates with such helpers, you just need to follow them.

When webpack runs, it will generate all static, optimized and pre-compiled assets in public/packs with a manifest file declaring the full URL pointing to the CDN. For example, if I fetch the /app/public/packs/manifest.json from the Heroku dyno directly, I will get something like this:

{
  "Roboto-Bold.woff": "//doz7rtw2u3wg4.cloudfront.net/packs/Roboto-Bold-eed9aab5449cc9c8430d7d258108f602.woff",
  "Roboto-Bold.woff2": "//doz7rtw2u3wg4.cloudfront.net/packs/Roboto-Bold-c0f1e4a4fdfb8048c72e86aadb2a247d.woff2",
  "Roboto-Light.woff": "//doz7rtw2u3wg4.cloudfront.net/packs/Roboto-Light-ea36cd9a0e9eee97012a67b8a4570d7b.woff",
  "Roboto-Light.woff2": "//doz7rtw2u3wg4.cloudfront.net/packs/Roboto-Light-3c37aa69cd77e6a53a067170fa8fe2e9.woff2",
  "Roboto-Medium.woff": "//doz7rtw2u3wg4.cloudfront.net/packs/Roboto-Medium-cf4d60bc0b1d4b2314085919a00e1724.woff",
  "Roboto-Medium.woff2": "//doz7rtw2u3wg4.cloudfront.net/packs/Roboto-Medium-1561b424aaef2f704bbd89155b3ce514.woff2",
  "Roboto-Regular.woff": "//doz7rtw2u3wg4.cloudfront.net/packs/Roboto-Regular-3cf6adf61054c328b1b0ddcd8f9ce24d.woff",
  "Roboto-Regular.woff2": "//doz7rtw2u3wg4.cloudfront.net/packs/Roboto-Regular-5136cbe62a63604402f2fedb97f246f8.woff2",
  "Roboto-Thin.woff": "//doz7rtw2u3wg4.cloudfront.net/packs/Roboto-Thin-44b78f142603eb69f593ed4002ed7a4a.woff",
  "Roboto-Thin.woff2": "//doz7rtw2u3wg4.cloudfront.net/packs/Roboto-Thin-1f35e6a11d27d2e10d28946d42332dc5.woff2",
  "application.css": "//doz7rtw2u3wg4.cloudfront.net/packs/application-09b53ce9ca3dd595ee99.css",
  "application.css.map": "//doz7rtw2u3wg4.cloudfront.net/packs/application-09b53ce9ca3dd595ee99.css.map",
  "application.js": "//doz7rtw2u3wg4.cloudfront.net/packs/application-799300612ff6d6595198.js",
  "application.js.map": "//doz7rtw2u3wg4.cloudfront.net/packs/application-799300612ff6d6595198.js.map",
  "home_page.js": "//doz7rtw2u3wg4.cloudfront.net/packs/home_page-ff3b49407a1d01592ad5.js",
  "home_page.js.map": "//doz7rtw2u3wg4.cloudfront.net/packs/home_page-ff3b49407a1d01592ad5.js.map"
}

So, if for some reason I had to create a new CDN distribution, you have to remember to update the CDN_URL variable on Heroku and redeploy your app so it regenerates the assets and this manifest file. It will just use those URLs when rendering the final HTML.

When a user opens your site, it will receive the HTML with URLs pointing to the CDN. The very first time it won’t have any cached assets, so it will ask your site for them. Your site must return the assets WITH the correct CORS headers so the CDN caches them with the headers and forwards those headers to the browser. The browser needs those headers because it will open from domain www.theconf.club, for example, but fonts are loading from doz7rtw2u3wg4.cloudfront.net, so it would raise a security warning and not load the fonts because they are in different domains. Hence the CORS headers the font provides, indicating that they are safe to load.

For your Rails app to return the proper headers, you need to add the rack-cors gem to your Gemfile. Then you must add a new configuration file at config/initializers/rack-cors.rb with:

if defined? Rack::Cors
  Rails.configuration.middleware.insert_before 0, Rack::Cors do
    allow do
      origins %w[
        https://theconf.club
        http://theconf.club
        https://www.theconf.club
        http://www.theconf.club
        https://theconf.herokuapp.com
        http://theconf.herokuapp.com
      ]
      resource '/assets/*'
    end
  end
end

When you deploy, you know it’s working correctly when you Curl an asset and it returns the Access-* headers like this:

$ curl -I -s -X GET -H "Origin: www.theconf.club" http://www.theconf.club/packs/Roboto-Regular-5136cbe62a63604402f2fedb97f246f8.woff2
HTTP/1.1 200 OK
Server: Cowboy
Date: Wed, 28 Jun 2017 17:44:41 GMT
Connection: keep-alive
Access-Control-Allow-Origin: www.theconf.club
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Expose-Headers: 
Access-Control-Max-Age: 1728000
Access-Control-Allow-Credentials: true
Last-Modified: Wed, 28 Jun 2017 17:06:03 GMT
Content-Type: application/font-woff2
Cache-Control: public, max-age=2592000
Vary: Origin
Content-Length: 64832
Via: 1.1 vegur

And if everything above is already in place, you should be able to see the headers being forwarded through the CDN, like this:

$ curl -I -s -X GET -H "Origin: www.theconf.club" http://doz7rtw2u3wg4.cloudfront.net/packs/Roboto-Regular-5136cbe62a63604402f2fedb97f246f8.woff2
HTTP/1.1 200 OK
Content-Type: application/font-woff2
Content-Length: 64832
Connection: keep-alive
Server: Cowboy
Date: Wed, 28 Jun 2017 17:45:18 GMT
Access-Control-Allow-Origin: www.theconf.club
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Expose-Headers: 
Access-Control-Max-Age: 1728000
Access-Control-Allow-Credentials: true
Last-Modified: Wed, 28 Jun 2017 17:06:03 GMT
Cache-Control: public, max-age=2592000
Via: 1.1 vegur, 1.1 86e9abdb4c15b9d3a542f9b93245e87e.cloudfront.net (CloudFront)
Vary: Origin
X-Cache: Miss from cloudfront
X-Amz-Cf-Id: tVkZ41RRr66iBT6atWTO_oeTY_jG0zCBFuXU8bKyClZDQ8kl-hDegA==

A CDN is the secret sauce that allows any content-based website to scale way beyond what your server can provide. It’s a huge cost-saving and it also makes for a much smoother user experience for your users.

One last caveat. The many Rails View Helpers such as image_tag allow you to add the image file name without an extension in development and they will correctly find the image. But on the server it will fail to render the template this way. As a rule of thumb ALWAYS fill in the entire filename and extension, for example image_tag("logo.png") instead of just image_tag("logo").

You can see how this fails if you open a console in Heroku and check out how it fails to derive the full image URL:

$ heroku run rails c                                                                                                                  
Running rails c on ⬢ theconf... up, run.8271 (Hobby)
Loading production environment (Rails 5.1.2)

irb(main):001:0> ActionController::Base.helpers.asset_path("icon-goals")
Sprockets::Rails::Helper::AssetNotFound: The asset "icon-goals" is not present in the asset pipeline.
    from (irb):1

irb(main):002:0> ActionController::Base.helpers.asset_path("icon-goals.png")
=> "//d134ipy19a646x.cloudfront.net/assets/icon-goals-b969b3b7325d33ad85a88dbb5b894832909ed738eea9964b9cf535646b93674b.png"

Adding Memcached

Talking about caching is always a complicated thing, which is why many people avoid even trying. Even though you can go really crazy with super granular configurations such as using Russian Doll Caching, just adding cache in a few spots can greatly benefit you. And it’s super easy to boot.

The first thing to do is add Memcachier to your Heroku application. It has a free-tier and for most small apps it should be enough.

Configuration is also trivial. Start by adding the following gems to your Gemfile:

group :production do
  gem 'rack-cors', require: 'rack/cors'
  gem 'rack-cache'
  gem 'dalli'
  gem 'kgio'
  gem 'memcachier'
end

Now you must edit your config/environments/production.rb like this:

config.cache_store = :dalli_store

client = Dalli::Client.new((ENV["MEMCACHIER_SERVERS"] || "").split(","),
                           :username => ENV["MEMCACHIER_USERNAME"],
                           :password => ENV["MEMCACHIER_PASSWORD"],
                           :failover => true,
                           :socket_timeout => 1.5,
                           :socket_failure_delay => 0.2,
                           :value_max_bytes => 10485760)
config.action_dispatch.rack_cache = {
  :metastore    => client,
  :entitystore  => client
}

Now, let’s say you have a block in your template that requires a bunch of records from your database. But you know that those records barely change. What can you do? One alternative is to cache the ActiveRecord query entirely like this:

class HomePageController < ApplicationController
  def index
    @selected_proposals = Rails.cache.fetch('selected_proposals', expires_in: 1.day) do
      Proposal.includes(:authors).where(selected: true).to_a
    end
  end
end

The #to_a is necessary because ActiveRecord queries are lazy. The #to_a forces it to fetch and it will be cached. Next time, it will not touch the database for an entire day!

I could also have added a cache do ... end block in the template itself. There are many options. Point is that it’s not as difficult as most people would think.

What makes caching difficult is adding expiration logic. And the rule of thumb is: never try to manually expire any cache. Just change the lookup key for something else and let the old data just die (memcached will take care of getting rid of unused old data).

You really want to read the Rails Guides on Caching. It really is not as difficult as you think and you can cache only the few snippets you know are performance-sensitive and leave the other parts that are highly dynamic and you’re unsure how to properly cache.

But as it’s super cheap, just use it right now.

Adding SSL support

If you have any security-sensitive transactions going on (ex. purchases) you want to use SSL. Again, many people avoid it because it’s usually difficult to even understand how to properly get a certificate.

Let’s Encrypt made the process super trivial. Kudos to them! And even better: it’s free! So, you don’t have any excuses to not have SSL.

And over Heroku, it’s even easier!

ACM (Automated Certificate Management) is enabled by default for all applications created after March 21, 2017 that are running on Hobby or Professional dynos. The following steps are for applications currently running on Free dynos, and for applications created before that date.

On the Free Tier Dynos, this is what you do:

heroku certs:auto:enable

Check status with heroku certs:auto.

Done, there is no step 2.

We used to have to use the complicated gem letsencrypt-rails-heroku, but now it’s just too easy.

Conclusion

I believe this covers the very basics of stuff you should be doing before deploying your small app to Heroku. For larger apps there are many more concerns that are beyond the scope of this post.

If you remember about more tips and tricks, please share in the comments section below.

The Blender community is so passionate and committed that they frequently produce high quality, almost Hollywood grade short movies inside Blender. The point is to stress test the tool and flush out bottlenecks and usability issues in a real world workflow.

This is primarily a post for “future me” to jump back into a single resource list. Being a 3D modeler is not my full time job, so I’ll have large gaps between Blender sessions. And I know I’ll regret it if I don’t dump my brain into a post while it’s still fresh :-)

Beginner First Steps

First things first. If you’re in this blog, you’re probably a programmer. And let me tell you that the Graphics folks see “usability” very differently from what we, programmers, usually think of. The sheer amount of customization, options, shortcuts and combinations will rival even Vim and Emacs users out there.

Oh, by the way, you’re going to need a real 3-button mouse. Touchpads are useless with Blender, and the Mac mouse is terrible. Any cheap PC mouse will do.

Out of the box, the main button is the right one, not the left one we’re used to. Change that in the user preferences to select with Left, and things start to make sense. While you’re there, enable Numpad emulation too.

By the way, it’s well worth having a keyboard with a numpad, or even a separate numpad. You can use the number row on top of your normal keyboard, but Blender was built assuming both an inverted 3-button mouse and a numpad.

If you have never studied Blender before, you will not figure things out just by randomly exploring the UI. The UI is useless until someone teaches you the ins and outs. There are hundreds of terms you just have no idea what they mean, such as Meshes, Edges, Seams, Nodes, Viewport, Subsurface, Modifiers, etc.

The main thing you MUST do before proceeding is watching this entire 9 part series from Blender Guru, called Blender Beginner Tutorial Series. Optionally you can slowly do the Intermediate Blender Tutorials later.

The Beginner Series will teach you enough that you’ll finally start feeling confident with the UI and tools. And don’t forget to print and hang this handy “cheat sheet”. You won’t believe how much easier your life becomes once you get used to the most important keyboard shortcuts.

Better Defaults

For historical reasons, some things are not how they should be. Knowledge in the 3D rendering field is evolving very fast.

The very first thing to do: change the default render engine from Blender Render to the Cycles Raytracing Engine.

Then, color grading. The default sRGB EOTF is basically wrong. You must download Sobotka’s filmic-blender configuration. If you’re on Arch Linux you can basically do:

pacaur -S filmic-blender-git

I created a script at ~/bin/filmic-blender with this:

env OCIO=/usr/share/blender/2.78/datafiles/filmic-blender/config.ocio blender

And I always start Blender from the terminal like this:

optirun ~/bin/filmic-blender

This does 2 things: first, it pre-configures OpenColorIO to use the Filmic replacement. Second, it enables the external GPU of my notebook to be available to Blender. Read my post on “Enabling Optimus NVIDIA GPU on the Dell XPS 15 with Linux, even on Battery” for more details. On Windows or Mac this is not necessary, but you’ll still need to load the filmic configuration.

Then, on the Scene tab you must reconfigure “Color Management” to be like this:

Then you need to configure Cycles. If you’re on Linux and Optimus is correctly installed as I explained before, you should have the CUDA option enabled in the User Preferences:

In the Render tab, you should have something like this:

In the Dimensions section, you’ll notice it has the Full HD (1920x1080 px) size but only 50% (so it will only render half the size). Increase it to 100%. If you want a 4K shot, increase the dimensions to 3840x2160 px. 4K makes it 4 times slower to render than 1080p, obviously.

In the Performance section you’ll see 2 input fields for “Tile size”. Blender will slice your full image into tiles, and each tile renders in parallel on an available CPU or GPU core. My notebook has 8 CPU cores, so 64 is a good size, because it will render 8 tiles of 64 pixels each in parallel.

The fewer cores you have, the larger you should make the tile sizes. For my NVIDIA GPU, I only have 2 available cores (and not a lot of video memory either!), so it’s worth bumping both fields to 512. On the GPU it only renders 2 tiles at once, and larger tiles optimize the render.

As you probably guessed, Blender Guru has a very useful “18 ways to speed up Cycles Rendering” tutorial.

These should cover the basic defaults.

You must think as a Photographer!

You will want to watch A LOT of online tutorials, because it’s really not obvious how to best use the tools. Another channel I really like is BornCG and CG Masters. Pick a few of their videos to get a more in-depth view on specific tools, modeling techniques and so on.

And really, you must practice as much as possible while studying a lot along the way. One important area is Photography. This is what you see when you select the Camera tab:

There’s a lot of customization you can do here. For example: Focal length: 35.00, which is what photographers know as a 35mm lens, a good default choice. You can also use a really wide angle such as 200mm or 300mm, and indoor shots, in small rooms, could use a 24mm or even 18mm lens. This article “Understanding Color Lenses” should give you the basics.

Then, you must understand “Depth of Field”. This can be done at this configuration before rendering, or you can simulate it after rendering (if you chose to separate the render in layers), in the Compositor.

Speaking of which, another way to control Depth of Field is reconfiguring “f-stop”, which is the measurement of exposure, or aperture. The default is “128.0”, which is “f/128”. As a reference, your iPhone 7s camera has an f/2.2 aperture. Again, let’s study more about this starting with the article “What’s the Best F-Stop?”

Taking a photo (or rendering a still, in our case) is a whole lot more than just point-and-click. You also have to worry about proper composition techniques such as the Rule of Thirds, the golden ratio, and so on. You can change that in the “Composition Guides” combo box as shown above.

You really should dive deep into the field of Photography to improve the final result of the renders. I’m an amateur and it’s really exciting to be able to apply real world techniques to 3D rendering.

Material Design and Physically-Based Render (PBR)

The golden standard in 3D modeling and rendering is certainly Disney/Pixar RenderMan. Every award winning Pixar movie was made with it.

But Blender learns fast. Every Pixar paper eventually becomes part of Blender itself. Material design, for example, has always been quite cumbersome in the tool. I did some of the tutorials myself, and creating materials with the proper real world characteristics, like proper Fresnel and the right dielectric versus metallic distinction, was a challenge.

If you subscribed to Blender Guru’s channel you should really watch the tutorials “How to Make Photorealistic PBR Materials - Part 1” and “Part 2”. And you will end up with this complicated Nodes configuration for PBR materials:

And Blender Guru just posted a new video introducing a feature for the upcoming Blender 2.79 (currently at 2.78): the implementation of the “Physically-Based Shader at Disney” paper as a proper and optimized new Blender Shader named “Principled Shader”. It’s quite literally the Ultimate Shader, because it makes creating and customizing realistic materials very easy, and compatible with Renderman and Substance.

Conclusion

I am still a beginner at Blender, there is a very long road to walk here. But it’s a very exciting environment and I am learning tons of new and useful stuff all the time. Anyone should try it!

Over time I hope I find the time to integrate the Blender workflow with other tools such as Unreal Engine or Unity3D to create interactive stuff as well.

This is by no means a complete tutorial or reference. The idea was to highlight a few things that are not immediately obvious when you start with Blender and that can give you a broader sense of what Blender can do.

If you want to go really in-depth in the customization, watch this CG Master setup video:

Where to Deploy? TL;DR: Heroku

Many people will first target the cheap choices. Usually EC2 micro instances or small Digital Ocean droplets. Unless you’re aware that you must constantly monitor and upgrade those instances, DON’T do it.

Instead choose a PaaS solution such as Heroku. It’s a no-brainer. Software in production is not a one-off thing. For security alone you should not do it by yourself unless you know how to harden an OS distribution. For example, most people don’t even know what fail2ban is. Don’t assume that because you use SSH with keypairs you’re secure. You’re not.

For example, did you know that we just went through a glibc security crisis? If you don’t and you haven’t touched your production servers in some time to upgrade all your components, you’re open, wide open. I had many clients who hired freelancers to implement and deploy their apps and then went without anyone checking. You’re all unsafe.

Heroku is no guarantee either, because app libraries get old, vulnerabilities get discovered, and you should upgrade them. Rails has an active security team releasing security patches all the time. If you haven’t been upgrading, you’re unsafe.

But 24x7 support is not cheap, if you have your own infrastructure or use an IaaS platform such as AWS EC2, you should have 24x7 personnel, this means at least 2 full-time system administrators/devops taking care of things. Or, you use a PaaS that at least keeps those basic sanitations in check and a part-time developer to at least keep upgrading your apps.

If you don’t, you’re opening your business to serious liability. And if you’re a developer, do the responsible thing: disclose this fact to your clients and let them make an informed choice. They can choose to stay cheap, but at least they know what this actually means.

Which web server? TL;DR: Passenger or Puma

Most Rails apps lack basic libraries that should be installed to make them work correctly.

I’ve seen people running production apps by just firing up rails server and nothing else! This is running the basic Webrick web server, in production! You must choose between Puma, Unicorn, Passenger. Unicorn actually does not protect your app against slow clients, so avoid it if you can.

If you’re in doubt, install Passenger and call it a day.

The most common choice nowadays is using Puma. But if you’re running under Heroku or using small instances, keep in mind your RAM usage. A normal Rails application consumes at least 150Mb to 200Mb or more depending on the size of your app. The smallest Heroku dyno has only 512Mb of RAM, that means you should not configure Puma or Unicorn to have more than 2 instances. I’d recommend going for the 2X Dyno (1GB) and have at most 3 instances (which means 3 possible concurrent requests being processed at once).

It’s not uncommon for your app to keep increasing RAM usage over time and once every couple of days you see R14 happening, then your dyno reboots and it starts working better for a while until it reaches the ceiling again.

If you don’t know why that’s happening, and it’s infrequent, you can temporarily use Puma Worker Killer - if you’re using Puma, of course - to keep monitoring your instances until they reach a certain lower ceiling and they automatically recycle before your users see the R14 errors.

You may also have heard of Out-of-Band GC. Just be warned that Puma in threaded mode won’t work well with it. If you’re using Unicorn, by all means do use it.

Measure, Measure, Measure. TL;DR: New Relic

You should always monitor your app. Be it with custom installed software such as Nagios, Munin, Zabbix, Zenoss, Ganglia, etc or at the very least the metrics that Heroku provides you, as in the image above.

If your instances are behaving strangely, you should take a look at the warnings. A frequent set of R14 errors means that your app’s memory consumption is growing over time and blowing the maximum amount of RAM available in your instance (a probable memory leaking). At the very least this means that you should decrease the number of concurrency/workers in your Puma/Unicorn and also increase the number of dynos to compensate if you do have enough traffic to justify it. But this is one metrics-oriented action that you can take because you have the information to make an informed decision.

But you should also be storing and indexing your logs using custom installed software such as Greylog2 or Logstash or using a SaaS alternative such as Papertrail. There are many reasons why an app might be leaking, or why everything seems fine in the metrics but you’re having random errors. Always query the logs for answers.

Better yet, install New Relic APM. You will have both the metrics, the automated alerts, the errors measurement and really deep diagnostics to see exactly what line in your source code is guilty for your poor performance or frequent errors or erratic behavior. If you’re in doubt, just install it, the basic plan is free anyway.

Some Rails Dependencies

You should NOT be using Rails below version 4.0 by now. 3.2 is still widely used but it will stop being supported soon. Do not use Rails 5.0 right now unless you’re experienced enough to know what to do. Anything from 4.0 to 4.2 should be ok, but be aware of the minor releases that fix security vulnerabilities.

You should NOT be using Ruby below version 2.2 by now. Security upgrades for 2.0 ended this February 2016. 2.1 was not a good stable release, but 2.2 and 2.3 are very good and you should be using them.

So the combination of Ruby 2.3.0 and Rails 4.2.5.2 (by March 2016) is the optimal choice for best stability, security and ecosystem support.

You should have at least the following dependencies installed by default:

• Rails 12 Factor gem
• Rack-Cache middleware
  • Dalli gem with Memcached or Memcachier - even if you’re not using fragment caching or AR caching, this is still useful at least for the Rack-Cache gem.
• Rack-Attack - read how to properly configure!
• Rack-Protection - read how to properly configure and what protections you want to activate, not everything, but at least CSRF and XSS.
• Sprockets 3.3+ - make sure you’re using the Sprockets version that fixes the slow speeds and makes it reasonably faster

Which Database? TL;DR: use Postgresql

Do NOT choose MongoDB or similar unless you have a very strong reason to and you are confident that you’re very good at what you’re doing and you will be sticking around to maintain what you deploy. Otherwise stick to Postgresql and the “pg” gem, you won’t regret it, nor will your client.

Do use small Redis instances (particularly SaaS options such as Heroku Redis ) with Sidekiq. You can choose to use the lighter Sucker Punch but be aware that it will increase the RAM usage of your instances considerably depending on the size of your queues and the serialized input data for the workers. It’s not always trivial how many Sidekiq workers you should have, but this calculator could help.

There are at least 2 big mistakes most people make using Sidekiq:

• Having heavy workers hitting your master database. For example a big analytics procedure fetching large sets of data while your main website also has heavy user activity writing data all the time. Definitely add a Follower database and point the Sidekiq workers (read-only) there for analytics, reports and similar workloads.
• Fetching large datasets in-memory and blowing your worker dynos. If you do anything similar to “YourModel.all.each { |r| … }” you’re shooting yourself in the foot. Rails has easy ways to fetch small sets in batch for you to process, use them.

Are you using a CDN? TL;DR: just do

This is easy, use AWS CloudFront or Fastly or something else, but USE a CDN. It’s a no-brainer.

Otherwise your assets will be served by your already small web dyno instances. And this is heavy lifting that’s better served from a much faster CDN. Your users will perceive orders of magnitude in usability by changing just a couple of configuration lines in your code.

If you implemented your Rails views, templates, stylesheets using the “image_tag”, “asset_path” helpers, it’s just automatic. Just do it already.

And while we’re on the subject of assets, if you happen to have image uploading and you’re using the simple way of posting a multipart form directly to your Rails app, you will have trouble because Heroku imposes - a correct - maximum of 30 seconds of timeout. If you have many users uploading many high-resolution and heavy sized images, they will see increasing amounts of timeouts.

Use the Attachinary gem to direct upload via Javascript, from the browser, to the Cloudinary service, completely bypassing your Rails app, which will just receive the ID once the upload finishes. Again, there is a very generous free plan and it’s so simple to implement that you must do it right away.

You laid off your developer, what to do? TL;DR: revoke access!

This is something that happens a lot: a small company needs to cut costs and lay off developers.

Make sure you revoke access. In AWS it’s a lot more convoluted if you don’t know your way through their IAM authorization tool. Or worse: if they have the private keys (.pem files) to your EC2 instances!! You will have to create new keypairs, deactivate the old EC2 instances and create new ones. A royal PITA.

You must change passwords to your DNS service, Github/Bitbucket organization, remove SSH keys from the .ssh/authorized_keys files in all your servers, etc.

Make sure your company has good legal support and make every collaborator, employee or 3rd party, sign a non-disclosure agreement, non-compete or confidentiality agreements.

You MUST have at least one key person in the company that has control over the keys, passwords and access to every service your company depends on to run. Otherwise don’t be surprised when your app goes offline.

And don’t fool yourself into thinking that just because an app is online and running it will keep that way for long. Security vulnerabilities are in the wild, it’s just a matter of time until some glitch puts your service down and you better have someone to put it back online for you if you don’t know how to do it.

Big Site? Congratulations, what to do now?

If your business is thriving, blooming, congratulations. You’re in the very very small percentage that actually made it.

Soon your brand new app will become that ugly, dreaded Legacy system. Worse, it’s probably one of those feared monoliths or even worse, you let a hipster developer create a spaghetti architecture full of unchecked microservices. You’re doomed either way.

This situation requires you to be grounded: there is no silver bullet, just business as usual.

You must keep ahead of the game, and the monitoring part I mentioned plays a big part to steer you through the many possible directions you can go. For example, for a short period of time you can increase the plans of your SaaS services such as databases, caches, queues, and also add more parallel web dynos.

While that will hold for a while (your metrics can help you estimate for how long), now you need to come up with a plan to optimize what you have. And no, rewriting everything is the very last thing you want to do, unless you intend to not have a life for the next couple of years.

Trust Pareto: in real life, 80% of the main problems can be solved with 20% of the effort. The main big tip: open New Relic - now loaded with real production data - and check the top worst performers and start from there. The first one you solve (be it an ugly N+1 query to your database, slow web service integration), will give you a lot of room to breathe.

Conclusion

What I just said is nothing but the tip of the iceberg in terms of Rails performance optimization. And I can assure you that there is a lot of room to improve without having to resort to rewriting everything in the next hip language out there. I recommend you buy Nate Berkopec’s “The Complete Guide to Rails Performance” to really learn your turf.

This is a very quick compilation that I just dumped out of my mind, but there is much more that we can consider. Shoot questions in the comments section and other important items that I may have overlooked.

Many tutorial series start introducing a new language by its syntax. I subverted the order. Elixir is not interesting because of its syntax. Erlang is interesting all by itself, because of its very mature, highly reliable, highly concurrent, distributed nature. But its syntax is not for the faint of heart. It’s not “ugly”, it’s just too different for those of us from the C school to easily digest. It derives from Prolog, and this is one small example of a Prolog exercise:

% P03 (*): Find the K'th element of a list.
%     The first element in the list is number 1.
%     Example:
%     ?- element_at(X,[a,b,c,d,e],3).
%     X = c

% The first element in the list is number 1.

% element_at(X,L,K) :- X is the K'th element of the list L
%    (element,list,integer) (?,?,+)

% Note: nth1(?Index, ?List, ?Elem) is predefined

element_at(X,[X|_],1).
element_at(X,[_|L],K) :- K > 1, K1 is K - 1, element_at(X,L,K1).

Erlang has a similar syntax, with the idea of phrases divided by commas and ending with a dot.

José Valim played it very smart: he chose the best of the available mature platforms and coated it with a layer of modern syntax and easier-to-use standard libraries. This is the same problem implemented in Elixir:

defmodule Exercise do
  def element_at([found|_], 1), do: found
  def element_at([_|rest], position) when position > 1 do
    element_at(rest, position - 1)
  end
end

If I copy and paste the code above in an IEx shell I can test it out like this:

iex(7)> Exercise.element_at(["a", "b", "c", "d", "e"], 3)
"c"

This simple exercise shows us some of the powerful bits of Erlang that Elixir capitalizes upon, such as pattern matching and recursion.

First of all, every function must be defined inside a module, which you name with defmodule My.Module do .. end. Internally it becomes the atom “Elixir.My.Module”. Nesting modules is just a longer name concatenated with dots.

Then you can define a public function with the def my_function(args) do .. end block, which is just a macro for the same def my_function(args), do: … construct. Private functions are declared with defp.

A function is actually identified by the pair of its name and its arity. So above we have element_at/2 which means it accepts 2 arguments. But we have 2 functions with the same arity: the difference is the pattern matching.

def element_at([found|_], 1), do: found

Here we are saying: the first argument will be an array, decompose it. The first element of the array will be stored in the “found” variable, the rest “_” will be ignored. And the second argument must be the number “1”. This is the description of the so-called “pattern”, and it should “match” the input arguments received. This is “call-by-pattern” semantics.

But what if we want to pass a position other than “1”? That’s why we have this second definition:

def element_at([_|rest], position) when position > 1 do

Now, the first argument again needs to be an array, but this time we don’t care about the first element, just the rest of the array without the first element. And any position other than “1” will be stored in the “position” variable.

But this function is special: it is guarded to only allow a position that is larger than 1. What if we try a negative position?

iex(8)> Exercise.element_at(["a", "b", "c", "d", "e"], -3)
** (FunctionClauseError) no function clause matching in Exercise.element_at/2
    iex:7: Exercise.element_at(["a", "b", "c", "d", "e"], -3)

It says that none of the arguments we passed match any of the clauses defined above. We could have added a third definition just to catch those cases:

def element_at(_list, _position), do: nil

Adding the underscore “_” before the variable name is the same as having just the underscore, but we are naming it just to make it more readable. Any arguments passed will just be ignored. And this is the more generic case if the previous 2 don’t match.

The previous line is the same as writing:

def element_at(_list, _position) do
  nil
end

I won’t dive into macros for now. Just know that there is more than one way of doing things in Elixir and you can define those different ways using Erlang’s built-in support for macros, dynamic code that is compiled at runtime. It’s the way of doing metaprogramming in Elixir.

Now, going back to the implementation, the first function can still look weird; let’s review it:

def element_at([_|rest], position) when position > 1 do
  element_at(rest, position - 1)
end

What happens is: when we call Exercise.element_at([“a”, “b”, “c”, “d”, “e”], 3) the first argument will pattern match with [_|rest]. The first element “a” is discarded and the new list [“b”, “c”, “d”, “e”] is stored as “rest”.

Finally, we recurse the call, decrementing the “position” variable. So it becomes element_at([“b”, “c”, “d”, “e”], 2). And it repeats until position becomes “1”, in which case the pattern matching falls to the other function defined as:

def element_at([found|_], 1), do: found

In this case the rest of the array is pattern matched and the first element, “c”, is stored in the “found” variable; the rest of the array is discarded. It only got here because the position matched as “1”, so it just returns the variable “found”, which contains the 3rd element of the original array, “c”.

This is all nice and fancy, but in Elixir we could have just done this other version:

defmodule Exercise do
  def element_at(list, position), do: Enum.at(list, position)
end

And we are done! Several tutorials will talk about how recursion and pattern matching to decompose lists solve a lot of problems, but Elixir gives us the convenience of treating lists as Enumerables and provides us a rich Enum module with very useful functions such as at/2, each/2, take/2, and so on. Just pick what you need and you’re managing lists like a boss.

Oh, and by the way, there is something called a Sigil in Elixir. Instead of writing the List of Strings explicitly, we could have done it like this:

iex(8)> ~w(a b c d e f)
["a", "b", "c", "d", "e", "f"]

Or, if we wanted a List of Atoms, we could do it like this:

iex(9)> ~w(a b c d e f)a
[:a, :b, :c, :d, :e, :f]

Lists, Tuples and Keyword Lists

Well, this was too simple. You really need the idea of pattern matching and basic types in your mind to make it flow. Let’s get another snippet from the Ex Manga Downloadr:

defp parse_args(args) do
  parse = OptionParser.parse(args,
    switches: [name: :string, url: :string, directory: :string],
    aliases: [n: :name, u: :url, d: :directory]
  )
  case parse do
    {[name: manga_name, url: url, directory: directory], _, _} -> process(manga_name, url, directory)
    {[name: manga_name, directory: directory], _, _} -> process(manga_name, directory)
    {_, _, _ } -> process(:help)
  end
end

The first part may puzzle you:

OptionParser.parse(args,
    switches: [name: :string, url: :string, directory: :string],
    aliases: [n: :name, u: :url, d: :directory]
  )

The OptionParser.parse/2 receives just 2 arguments: 2 arrays. If you come from Ruby it feels like it’s a Hash with optional brackets, translating to something similar to this:

# this is wrong
OptionParser.parse(args,
    { switches: {name: :string, url: :string, directory: :string},
      aliases: {n: :name, u: :url, d: :directory} }
  )

This works in Ruby, but it is not the case in Elixir. There are optional brackets, but not where you think they are:

# this is the correct, more explicit version
OptionParser.parse(args,
    [
      {
        :switches,
        [
          {:name, :string}, {:url, :string}, {:directory, :string}
        ]
      },
      {
        aliases:
        [
          {:n, :name}, {:u, :url}, {:d, :directory}
        ]
      }
    ]
  )

WHAT!?!?

Yep, the second argument is actually an array with elements that are Tuples paired with an atom key and value, and some of the values are themselves arrays with tuples.

1. in Elixir, Lists are what we usually call an Array, a Linked-List of elements. Linked-Lists, as you know from your Computer Science classes, make it easy to insert and remove elements.

2. in Elixir, Tuples are immutable fixed lists with fixed positions, with elements delimited by the brackets “{}”

If the previous example was just too much, let’s step back a little:

defmodule Teste do
  def teste(opts) do
    [{:hello, world}, {:foo, bar}] = opts
    IO.puts "#{world} #{bar}"
  end
end

Now we can call it like this:

iex(13)> Teste.teste hello: "world", foo: "bar"
world bar

Which is the same as calling like this:

iex(14)> Teste.teste([{:hello, "world"}, {:foo, "bar"}])
world bar

This may confuse you, but it’s very intuitive. You can just think of this combination of Lists ("[]") with Tuple elements containing a pair of atom and value ("{:key, value}") as behaving almost like Ruby Hashes being used for optional named arguments.

Then, we have the Pattern Match section in both previous examples:

case parse do
  {[name: manga_name, url: url, directory: directory], _, _} ->
    process(manga_name, url, directory)
  {[name: manga_name, directory: directory], _, _} ->
    process(manga_name, directory)
  {_, _, _ } ->
    process(:help)
end

And

[{:hello, world}, {:foo, bar}] = opts

The last example is just decomposition. The previous example is pattern matching and decomposition. You match based on the atoms and positions within the tuples within the list. You match from the more narrow case to the more generic case. And in the process, the variables in the pattern are available for you to use in the matching case clause.

Let’s understand the meaning of this line:

{[name: manga_name, url: url, directory: directory], _, _} -> process(manga_name, url, directory)

It is saying: given the results of the OptionParser.parse/2 function, it must be a tuple with 3 elements. The second and third elements don’t matter. But the first element must be a List with at least 3 tuples. And the keys of each tuple must be the atoms :name, :url, and :directory. If they’re there, store the values of each tuple in the variables manga_name, url, and directory, respectively.

This may really confuse you in the beginning, but this combination of a List of Tuples is what’s called a Keyword List, and you will find this pattern many times, so get used to it.

Keyword Lists feel like a Map, but a Map has a different syntax:

list = [a: 1, b: 2, c: 3]
map = %{:a => 1, :b => 2, :c => 3}

This should summarize it:

iex(1)> list = [a: 1, b: 2, c: 3]
[a: 1, b: 2, c: 3]
iex(2)> map = %{:a => 1, :b => 2, :c => 3}
%{a: 1, b: 2, c: 3}

iex(3)> list[:a]
1
iex(4)> map[:a]
1

iex(5)> list.a
** (ArgumentError) argument error
    :erlang.apply([a: 1, b: 2, c: 3], :a, [])
iex(5)> map.a
1

iex(6)> list2 = [{:a, 1}, {:b, 2}, {:c, 3}]
[a: 1, b: 2, c: 3]
iex(7)> list = list2
[a: 1, b: 2, c: 3]

Keyword Lists are convenient as function arguments or return values. But if you want to process a collection of key-value pairs, use a dictionary-like structure, in this case a Map, especially if you need to search the collection using the key. They look similar, but the internal structures are not the same. A Keyword List is not a Map; it’s just a convenience for a static list of tuples.

Finally, if this pattern matches the parse variable passed to the case block, it executes the statement process(manga_name, url, directory), passing the 3 variables captured in the match. Otherwise it proceeds to try the next pattern in the case block.

The idea is that the “=” operator is not an “assignment”, it’s a matcher: you match one side with the other. Read the error message when a pattern is not matched:

iex(15)> [a, b, c] = 1
** (MatchError) no match of right hand side value: 1

This is a matching error, not an assignment error. But if it succeeds this is what we have:

iex(15)> [a, b, c] = [1, 2, 3]
[1, 2, 3]
iex(16)> a
1
iex(17)> c
3

This is List decomposition. It so happens that in the simple case it feels like a variable assignment, but it’s much more complex than that.

Pipelines

We use exactly those concepts of pattern matching on the elements returned from the HTML parsed by Floki in my Manga Downloadr:

Floki.find(html, "#listing a")
|> Enum.map(fn {"a", [{"href", url}], _} -> url end)

The find/2 takes an HTML string from the fetched page and matches against the CSS selectors in the second argument. The result is a List of Tuples representing the structure of each HTML Node found, in this case, this pattern: {“a”, [{“href”, url}], _}

We can then Enum.map/2. A map is a function that receives each element of a list and returns a new list with new elements. The first argument is the original list and the second argument is a function that receives each element and returns a new one.

One of the main features of the Elixir language that most languages don’t have is the Pipe operator ("|>"). It behaves almost like UNIX’s pipe operator “|” in any shell.

In UNIX we usually do stuff like “ps -ef | grep PROCESS | grep -v grep | awk ‘{print $2}’ | xargs kill -9”

This is essentially the same as doing:

ps -ef > /tmp/ps.txt
grep mix /tmp/ps.txt > /tmp/grep.txt
grep -v grep /tmp/grep.txt > /tmp/grep2.txt
awk '{print $2}' /tmp/grep2.txt > /tmp/awk.txt
xargs kill -9 < /tmp/awk.txt

Each UNIX process can receive something from standard input (STDIN) and output something to standard output (STDOUT). We can redirect the output using “>”. But instead of doing all those extra steps and creating all those extra garbage temporary files, we can simply “pipe” the STDOUT of one command to the STDIN of the next command.

Elixir uses the same principles: we can simply use the returning value of a function as the first argument of the next function. So the first example of this section is the same as doing this:

results = Floki.find(html, "#listing a")
Enum.map(results, fn {"a", [{"href", url}], _} -> url end)

In the same ExMangaDownloadr project we have this snippet:

defp process(manga_name, url, directory) do
  File.mkdir_p!(directory)
  url
    |> Workflow.chapters
    |> Workflow.pages
    |> Workflow.images_sources
    |> Workflow.process_downloads(directory)
    |> Workflow.optimize_images
    |> Workflow.compile_pdfs(manga_name)
    |> finish_process
end

And we just learned that it’s the equivalent of doing the following (I’m cheating a bit because the 3 final functions of the workflow are not transforming the input “directory”, just passing it through):

  defp process(manga_name, url, directory) do
    File.mkdir_p!(directory)

    chapters  = Workflow.chapters(url)
    pages     = Workflow.pages(chapters)
    sources   = Workflow.images_sources(pages)
    Workflow.process_downloads(sources, directory)
    Workflow.optimize_images(directory)
    Workflow.compile_pdfs(directory, manga_name)
    finish_process(directory)
  end

Or this much uglier version that we must read in reverse:

defp process(manga_name, url, directory) do
  File.mkdir_p!(directory)
  finish_process(
    Workflow.compile_pdfs(
      Workflow.optimize_images(
        Workflow.images_sources(
          Workflow.pages(
            Workflow.chapters(url)
          )
        )
      ), manga_name
    )
  )
end

We can easily see how the Pipe Operator “|>” makes any transformation pipeline much easier to read. Anytime you are starting from a value and passing the results through a chain of transformations, you will use this operator.

Next Steps

The concepts presented in this article are the ones I think most people will find the most challenging upon first glance. If you understand Pattern Matching and Keyword Lists, you will understand all the rest.

The official website offers a great Getting Started that you must read entirely.

From intuition you know most things already. You have “do .. end” blocks, but you may not yet know that they are just convenience macros to pass a list of statements as an argument inside a Keyword List. The following blocks are equivalent:

if true do
  a = 1 + 2
  a + 10
end

if true, do: (
  a = 1 + 2
  a + 10
)

if true, [{:do, (
  a = 1 + 2
  a + 10
)}]

Mind-blowing, huh? There are many macros that add syntactic sugar using the primitives behind it.

For the most part, Valim made the powerful Erlang primitives more accessible (Lists, Atoms, Maps, etc.) and added higher abstractions using macros (do .. end blocks, the pipe operator, keyword lists, shortcuts for anonymous functions, etc.). This precise combination is what makes Elixir very enjoyable to learn. It’s like peeling an onion: you start with the higher abstractions and discover macros of simpler structures underneath. You see a Keyword List first and discover Lists of Tuples. You see a block and discover another Keyword List disguised by a macro. And so on.

So you have a low barrier to entry and you can go as deep as you want into the rabbit hole, all the way to extending the language.

Elixir provides a very clever language design on top of the 25-year-old mature Erlang core. This is not just clever, it’s the intelligent choice. Keep learning!

I’m showing snippets of code from a demonstration app and you can see the code at my Github repo and you can also see the app up and running here, thanks to Heroku’s free accounts.

I hope you enjoy it!

Most of this was based on Cocoanetics article about universal static libraries. So, if you’ve paid attention to my previous article, you saw this screenshot:

I said that I only had these targets configured: CocoaOniguruma, Kiwi, Rubyfication and RubyficationTests. But there are 3 others: CocoaOniguruma SIM, Rubyfication SIM, and Build & Merge Libraries. The reason is simple:

• The “CocoaOniguruma” Target builds the libCocoaOniguruma.a binary that’s compatible with the ARM processor for iOS
• The “CocoaOniguruma SIM” Target builds the libCocoaOnigurumaSimulator.a binary that’s compatible with the i386 processor for the local iPhone Simulator
• The “Rubyfication” Target builds the libRubyfication.a binary that’s compatible with the ARM processor for iOS
• The “Rubyfication SIM” Target builds the libRubyficationSimulator.a binary that’s compatible with the i386 processor for the local iPhone Simulator
• The “Build & Merge Libraries” Target merges the corresponding particular binaries of each target into a single Universal (Fat) Binary that we can easily distribute and reuse.

Concepts and History

Some explanation is in order. When you’re developing iOS applications, you can test it directly on your iPhone device or within the Simulator. Now, Apple was very clever: any other vendor in the market will try to first create an ARM processor emulator to run on top of your i386 processor. Then it will get all the binaries for ARM and run within this emulator. The OS itself will remain compiled for ARM processors and run within the emulator.

Now, this is dead slow, impractical. Anyone that has experienced an emulation environment like this knows how ridiculous it is. Don’t confuse it for VMWare or Parallels solutions, which are fast because they are an emulated environment for the same processor , so you can run Windows on top of your Mac because the processors and operating systems now support VT-x, which means you mostly don’t have to emulate the processor. Now, every smartphone and tablet on the market uses an ARM processor, which has nothing to do with i386.

So, how did Apple deliver a super-fast iPhone/iPad emulator that runs at real-time speed on your Mac? Simple, it didn’t. It is called “Simulator” and not “Emulator” for a reason: everything that runs within the Simulator is compiled for i386, not for ARM. So what you’re running is an actual binary that runs natively over your Mac! No emulation required. The iOS is very portable. The same way Mac OS X was able to transition from the Power PC to Intel back in 2005, the iOS can do the same trick as they are basically the very same operating system.

When you choose the iPhone scheme in XCode, it compiles for ARM and uploads the bits to your iPhone device to run the application. When you choose the Simulator scheme in XCode, it compiles for i386, uploads the bits to your Simulator and runs natively as any other application in your Mac.

Now, going back to the main issue: when I distribute a binary of my Static Library, I have to remember that the developer will be linking against my library to deploy for both the ARM device (iPhone/iPad) and the Simulator (i386). So I would have to deliver at least 2 binary files. But Apple is even smarter than that. Actually, NeXT was. When they first transitioned the NeXTStep operating system from Motorola to Intel processors back in the late 80’s, they created Fat Binaries, which is essentially one binary that contains both processor-specific bits in one single package. When Apple transitioned from the Power PC to Intel they renamed it to Universal Binaries. And that’s essentially what we need to build now.

Operations

We now understand what a Universal Binary is. To make it easier, I right-clicked over the “Rubyfication” and “CocoaOniguruma” targets and duplicated them. They will be created as “Rubyfication copy” and “CocoaOniguruma copy”. We can change the “Product Name” in the build settings of each for a more reasonable name:

In my case I renamed them to “RubyficationSimulator” and “CocoaOnigurumaSimulator”. That will give me both “libRubyficationSimulator.a” and “libCocoaOnigurumaSimulator.a”. As you can see in the Products group:

Important: remember that the Rubyfication target had CocoaOniguruma as a target dependency. You will need to change the “Rubyfication SIM” target to point to the new “CocoaOniguruma SIM” target! The other thing is that you will need to force both new targets to compile to “Latest Mac OS X” in the “Base SDK" option in the Build Settings of each, and “32-bit Intel” in the “Architectures” build option. This will make them compile for i386 processors. The original targets should have their “Base SDK" to “Latest iOS” and “Architectures” to “Standard (armv6 armv7)”.

Now, we need to create a new target of the kind “Aggregate” :

I named it “Build & Merge Libraries”. In the “Build Phases” tab you will start with just the “Target Dependencies” phase. You just need to add the new “Rubyfication SIM” and “CocoaOniguruma SIM” targets. Then you need to add 3 more phases, one for “Run Script”, another to “Copy Files” and a last “Run Script”.

In the “Copy Files” phase I have just added all the public headers that I want to distribute together with the universal binary library. This is because the other developers will need to add those header files into their projects in order to be able to compile against my library. Now notice that I am copying them to an “Absolute Path” that states ${TARGET_BUILD_DIR}/../Rubyfication.

That’s where we come to the previous “Run Script” phase that should have the following code:

# 1. make a new output folder
mkdir -p ${TARGET_BUILD_DIR}/../Rubyfication

# 2. combine lib files for various platforms into one
lipo create "${TARGET_BUILD_DIR}/../Debug-iphoneos/libRubyfication.a" "${TARGET_BUILD_DIR}/../Debug-iphonesimulator/libRubyfication.a" -output "${TARGET_BUILD_DIR}/../Rubyfication/libRubyfication${BUILD_STYLE}.a"

The first thing it does is create this new “Rubyfication” directory. The second command uses the lipo command that merges 2 processor-dependent binaries into a universal binary. Pay attention to the PATHs if you’re reusing this script somewhere else. At least with XCode 4 that’s where it creates the binaries of each target:

• ${TARGET_BUILD_DIR}/../Debug-iphoneos/libRubyfication.a – the ARM version
• ${TARGET_BUILD_DIR}/../Debug-iphonesimulator/libRubyfication.a – the i386 version
• ${TARGET_BUILD_DIR}/../Rubyfication/libRubyfication-Debug.a – the resulting universal binary we created

Finally, the last “Run Script”, after the “Copy Files” phase described above, requires the following script:

ditto c -k --keepParent "${TARGET_BUILD_DIR}/../Rubyfication" "${TARGET_BUILD_DIR}/../Rubyfication.zip"

–

It just creates a ZIP file with the universal binary library and its companion public header files. Any other developer can get this zip file, unzip it and add the files to their own projects now. If you want to find where this ZIP file is, the easiest way is to go to the project viewer (the left side pane) in XCode, open the “Products” group, right-click over the “libRubyfication.a” file (or any other resulting file) and choose “Show in Finder”. Then you can navigate one folder up in the hierarchy (to the “Products” folder) and you will see something like this:

And there you go: there’s your ZIP file with your brand new redistributable universal binary!

Using the Universal Binary

In order to demonstrate how to use this distributable ZIP file, I have created a very simple, bare-bone iOS project called ObjC_OnigurumaDemo that you can download from Github and run in your own iOS device.

As you can see in the screenshot below, I just unzipped the ZIP within a “Dependencies” folder in my iOS project and added the universal binary “libRubyfication-Debug.a” within the Library Linking Build Phase:

This allows me to just use anything from this library in my project, in particular a piece of code that uses the Oniguruma regular expressions:

- (IBAction)runRegex:(id)sender {
    OnigRegexp* regex = [OnigRegexp compile:[regexPattern text]];
    OnigResult* res = [regex match:[initialText text]];
    NSMutableString* tmpResult = [NSMutableString stringWithString:@""];
    for(int i = 0; i < [res count]; i++) {
        [tmpResult appendString:@"("];
        [tmpResult appendString:[res stringAt:i]];
        [tmpResult appendString:@")"];
    }
    [result setText:tmpResult];
}

This demonstration application has a text-field called “initialText”, where you can type any string. Then you can prepare a Regular Expression in the “regexPattern” text-field and when you hit the “Run” button, it will trigger the action above that will run the Regular Expression against the initial text and write the matches within parenthesis in the “result” text view. The application looks like this:

And, voilá! Ruby 1.9-like Regular Expression, directly from Oniguruma, within an iOS Application!

The idea of this pet project is to be a Static Library that I can easily add to any other project and have all of its features. In this article I’d like to present how I am organizing its many subprojects within one project (and I am accepting any suggestions and tips to make it better as I am just learning how to organize things within Obj-C projects) and talk about a gotcha that took me hours to figure out and might help someone else.

To make this exercise even more fun, I also added a separate target for my unit testing suite (and see how XCode supports tests), then another target for the Kiwi BDD testing framework for Obj-C, and another one for CocoaOniguruma as I have just explained in my previous article.

I’ve been playing with ways of reorganizing my project and I realized that I was doing it wrong. I was adding all the source files from my “Rubyfication” target into my Specs target. So everything was compiling fine, the specs were all passing, but the way I defined dependencies was wrong. It is kind of complicated to understand at first, but it should be something like this:

• CocoaOniguruma Target: should be a static library, with no target dependencies and no binary libraries to link against, just a dependency to the standard Foundation framework. It exposes the OnigRegexp.h, OnigRegexpUtility.h and oniguruma.h as public headers.
• Kiwi Target: should be another static library, with no target dependencies and no binary libraries to link against, just having the Foundation and UIKit framework dependencies.
• Rubyfication: should be another static library, with CocoaOniguruma as a target dependency, linking against the libCocoaOniguruma.a binary and depending on the Foundation framework as well. It exposes all of its .h files as public headers.
• RubyficationTests: should be a Bundle which was created together with the Rubyfication target (you can specify whether you want a unit test target when you create new targets), with both Kiwi and Rubyfication targets as dependencies, linking against the libKiwi.a and libRubyfication.a binaries, and the Foundation and UIKit frameworks as well.

If you keep creating new targets manually, XCode 4 will also create a bunch of Schemes that you don’t really need. I keep mine clean with just the Rubyfication scheme. You can access the “Product” menu and the “Edit Scheme” option. Then my Scheme looks like this:

I usually configure all my build settings to use “LLVM Compiler 2.0” for the Debug settings and “LLVM GCC 4.2” for the Release settings (actually, I do that for precaution as I am not aware if people are actually deploying binaries in production compiled from LLVM).

I also set the “Targeted Device Family” to “iPhone/iPad” and I try to make the “iOS Deployment Target” to “iOS 3.0” whenever possible. People usually leave the default one which will be the latest release – now at 4.3. Be aware that your project may not run on older devices that way.

Finally I also make sure that the “Framework Search Paths” are pointing to these options:

"$(SDKROOT)/Developer/Library/Frameworks"  
"${DEVELOPER_LIBRARY_DIR}/Frameworks"  

Everything compiles just fine that way. Then I can press “Command-U” (or go to the “Product” menu, “Test” option) to build the “RubyficationTests” target. It builds all the target dependencies, links everything together and runs the final script to execute the tests (you must make sure that you are selecting the “Rubyfication – iPhone 4.3 Simulator” in the Scheme Menu). It will fire up the Simulator so it can run the specs.

But then I was receiving:

Test Suite '/Users/akitaonrails/Library/Developer/Xcode/DerivedData/Rubyfication-gfqxbgyxicfpxugauehktilpmwzv/Build/Products/Debug-iphonesimulator/RubyficationTests.octest(Tests)' started at 2011-04-24 02:16:27 +0000  
Test Suite 'CollectionSpec' started at 2011-04-24 02:16:27 +0000  
Test Case '-[CollectionSpec runSpec]' started.  
2011-04-23 23:16:27.506 otest[40298:903] [__NSArrayI each:]: unrecognized selector sent to instance 0xe51a30  
2011-04-23 23:16:27.508 otest[40298:903] ***** Terminating app due to uncaught exception 'NSInvalidArgumentException', reason: '[__NSArrayI each:]: unrecognized selector sent to instance 0xe51a30'  

It says that an instance of NSArray is not recognizing the selector each: sent to it in the CollectionSpec file. It is probably this snippet:

# import "Kiwi.h"  

# import "NSArray+functional.h"  

# import "NSArray+helpers.h"  

# import "NSArray+activesupport.h"

SPEC_BEGIN(CollectionSpec)

describe(@"NSArray", ^{  
 __block NSArray* list = nil;

context(@"Functional", ^{ beforeEach(^{ list = [NSArray arrayWithObjects:@"a", @"b", @"c", nil]; }); 

it(@"should iterate sequentially through the entire collection of items", ^{ NSMutableArray* output = [[NSMutableArray alloc] init]; 

[list each:^(id item) { [output addObject:item]; }];

[[theValue([output count]) should] equal:theValue([list count])]; });
…