Building Twice: A clone of Once by 37signals

When Campfire - the first Once product - came out, a few of us at Ruby Zagreb pitched in to buy a copy.

Prometheus had brought fire from Mount Olympus, and we came to see the blaze. We were finally seeing how the people at 37signals - the birthplace of Rails - build Rails apps. And as a bonus, we could finally ditch our free Slack Channel!

This is a super elegant way to distribute apps! But how did it work? I wasn’t sure so I decided to replicate it and see.

Just like last time, I started to unravel this ball of yarn by following a thread - the shell script.

This downloads a binary for your OS and CPU architecture, installs it, and then runs it passing in your license key.

The first one was the same as the download URL, the second one obviously verifies something but I didn’t know what. My guess is for the password reset functionality (look at once-cli/internal/cmd/password_reset.go) because it interpolates a number at the end (that's the %d). The third one looks like a private Docker registry.

Can I login to the Docker registry?

I was curious about the validation token as it was obviously a Base64 string, but decoding it returned complete gibberish - it doesn't even look like unicode - so I assume that it's either completely random or an encrypted payload. Maybe that's what the verify endpoint is for?

My guess is that the token is used to update the "ssl_domain" field with the Once auth server after the install completes or during the DNS check. That would mean that the install endpoint probably also responds to a POST request.

Anyway, I now had a good understanding of how Once works.

The CLI handles Docker installation and configuration on the client, pulling and running of product Docker images, product container management, automatic-updates, backups, restores, and a few other things.

The private Docker Registry is, well, just a Docker Registry... It stores and distributes Docker images.

The license key you get is used as an access token to the registry. With it the CLI can pull images from the registry. That token probably grants access to a single repository in the registry - just for the product you purchased.

Now the fun part, making a clone of Once.

I decided to call this project "Twice" as a joke on the fact that it's a clone of Once - it's a second implementation. The source code is available on GitHub if you want to explore it, build, modify, or run Twice for yourself.

My main motivation is to learn more about how Once is set up, but a nice side effect is that I'll get a distribution system out of it - in the case that I decide to make an app and sell it. With that in mind, my primary goal is to implement just the setup CLI command. I'll work on everything else later.

Just like with Simpliki, I'll start from the center and work myself out. In the case of Twice the center is the CLI app - specifically the setup command.

As I've been working with Go at work lately, I felt confident in using it for the CLI. This would be a nice exercise to sharpen my Go skills. Otherwise I'd probably go with Rust as I have more experience with it, or I'd give Tebako a try - a new way to package Ruby apps into a single binary.

I like the version with the TUI more - it feels refined - and I think I'll revisit it once I'm more comfortable with Go and Bubble tea (the library that renders the TUI).

As I was building the CLI I started the Auth app and mocked a few endpoints just to get the setup command done. I didn't implement any UI and relied heavily on "bin/rails db:fixtures:load" to give me some data to work with. These endpoints were plain Rails controllers that rendered JSON.

The models I had for Twice

With most of the CLI out of the way, and with some of the Auth app done I turned my attention to the Docker Registry.

I liked the idea of having a Registry that's written in Rails so I tried Portus, but I couldn't get it to run locally - there are multiple known issues and the project was archived 2 years ago.

Harbor is a conglomeration of micro services. When I saw that I had to run 4 or more containers just to get the thing going I gave up.

All I had to do to get the registry working is to generate a self-signed certificate

Now the only thing left was to finish the Auth server.

Notice that the token is an object. This provides a nice domain language (DDD domain language) that makes it easier to work with, and reason about, the token. If I want the duration or the issued at time I can ask the token for it; if I want to turn it into a string I can do that too.

At this point I noticed that I didn't implement a way to push images to the registry. To fix that I introduced a new type of user - the Developer. STI made the most sense for this, so I converted the customers table to a users table, added a type column and a few extra columns.

The models in Twice after adding developers

Unlike Customers, Developers login with a password tied to their account and they get full access to the registry.

Notice that I strayed a bit from 37signals' implementation when it comes to downloading the binary. I decided to separate that out into another controller action because the install endpoint already does too many things in my opinion, and adding file sending to that seems like way too much responsibility for one endpoint.

I also made the decision that the auth server would directly send the file to the client instead of e.g. redirecting to something like S3. This makes it easier to self-host twice, and due to a trick it’s no less performant.

It assumes that the requested binary will be called "twice-#{platform}-#{arch}", then it goes and checks if such a file exists in the storage directory, and if it does it sends it.

The download endpoint in action

In production this won't actually stream the file from Ruby, instead it sets a special header that tells Thruster to send the file which makes things way more efficient.

Third, I added authentication using the new auth generator in Rails 8, and a UI for managing customers, developers, products and licenses.

And that was it. Twice was done. Here is the demo

Some loose thoughts

When writing about building Simpliki I left out an important part - what I intentionally didn't do.

For Twice, I intentionally didn't implement domain name tracking as I think that it's not important. It can't prevent people from running the docker container how and where they want. It would add complexity and I don't see the benefit of it, so I ditched it.

I do see the utility in all the backup and management commands that the Once CLI has, which that I didn't implement in Twice. I intend to return to that at some point. But they aren't important for distributing apps so I skipped them.

Twice, currently, has the same problem as Once - it doesn't play well with other apps or Kamal. This isn't a problem if you rent a VPS specifically to run a Once app, but if you have a large bare metal machine like me then this is cumbersome. I'd like to change it so that it deploys kamal-proxy and then proxies requests to different apps through it. This would allow it to run multiple apps on the same server.

This would make it more versatile - but, again, that's way beyond the scope of creating a clone to learn how Once works.

I liked working with Go. After years of using Rust, having a garbage collector and not having to think about results, unwrapping, lifetimes or borrowing was a breath of fresh air. Though, the way it declares modules still doesn't sit right with me. If you didn't look at the source code, each directory is its own module, and all files in the directory get essentially concatenated together into that module at compile time. It works, and I can't point out any problems with that, but it feels weird.