DEV Community: Krzysztof Tarnowski

Starting small and opting for “good enough” in a startup

Krzysztof Tarnowski — Sun, 11 Jul 2021 17:33:12 +0000

At the most recent company I co-founded, where we’re making a product for Instagram influencers 📷, we made a conscious decision to start small in terms of features, headcount, money and time. I want to share with you a short story of our product’s development and convince you that “small” and “good enough” is often the way to go. Why? Because it simply lets you focus on things that actually matter.

Early decisions

We started with an idea of building a product for Instagram users that would let them devote more time to creating engaging content their followers (and brands) love. In the long term, the product would have to offer advanced features that would take a bit of time to develop. Being ambitious in this context is perfectly fine, but we knew we had to start somewhere and first build, then test in the wild, a proof-of-concept that would serve as a platform upon which we could build bigger things.

To borrow naming conventions from Marvel’s MCU plan, our “Phase I” focused on validating key technical assumptions we’ve started with. The prototype developed at this stage was very crude, engineering-wise, and didn’t even have a UI of any sorts. It didn’t take long to develop and helped us better understand the technicalities of the problem we were trying to solve.

Next was “Phase II”, where the product’s featureset was limited to only the most sought-after, low-hanging automation tasks that we could ship to get the ball rolling. On the engineering side, we cut costs and saved time wherever possible. For example, instead of developing native versions of our desktop app for macOS, Windows and Linux, we opted for the Electron ecosystem. This meant we could develop the app once and distribute it to multiple platforms from a single codebase. What’s more, instead of building our very own auto-update system for the app, we could lean on existing libraries and tools (Open Source ❤️). In conjunction with Amazon S3 for hosting binaries (installers and update files), this also meant we didn’t have to spend a dime to get off the ground and move to validation with customers.

The “start small” mentality also extended to other parts of running a software company. For example, when it comes to website and email hosting, Zenbox has proven to be extremely cost effective and good enough for our use case. Even WordPress, which honestly I was not a huge fan of, later on allowed us to build the whole website, including checkout flow for subscription plans and invoicing, without too much of an effort. The website works well and looks good on the outside (ready-to-use, commercial WP themes!), and even though overall it may not be an engineering state-of-the-art, it serves its purpose really well.

One thing of note here is, while we cut corners whenever and wherever possible, we made sure to lay the groundwork for the future. In particular, each technical component is reasonably maintainable and swappable. The desktop app, for example, has a modular architecture and is not directly tied to Electron or the desktop itself, giving us a lot of options for what we have laid out in our roadmap.

Overall, the time saved here and there allowed us to safely focus on other challenges that come with building a product.

Early adopters

You’re in a good spot when customers tell you what they think about your product and their experience in general. Without that precious feedback, you’re essentially flying in the dark, so make sure you’re doing literally everything you can to get it. Be prepared for a good fight, as nowadays many things fight for customer’s attention, and cherish every effort on the customer’s part to talk to you about your product.

In our case, we enrolled our friends and friends of friends to test out prototypes and tell us about their experience. The feedback we’ve received was not only humbling, since it tested our assumptions about the needs of our potential customers, but also encouraging (we learned something!). We were even lucky to hear people say they experienced “wow!” moments on their journey with the product. At the end of this stage, a few weeks into development, we had a piece of software we could say was good enough to give into the hands of a broader audience. Naturally, the product backlog had quite the number of items in it, including bugs to squash 🐞, but doing anything more than that would mean delaying the launch. To paraphrase Reid Hoffman, if you’re happy with your product at launch, it means you waited too long to ship.

The launch was also “small”. There are plenty of software and hardware stack combinations people use, so we made the product available only to a limited number of people (private beta), with potential customers having to subscribe to a waitlist. It gave us precious time to thoroughly fix issues as they pop up.

Perfect is the enemy of good

I applied the “good enough” approach to hard engineering as well. In one case, we wanted for the desktop app to be properly packaged, so OS (Windows, macOS) would identify our software as safe to run. It was important to us, since it would add to the credibility of the product and help build trust. Unfortunately, I ran into an issue with macOS app notarization that took me some time to investigate. I came up with a solution that was a bit crude and involved monkey-patching one of the libraries used by our build system. At that point I faced a choice:

Spend more time on this issue and try to get to the root cause of the problem, potentially arriving at a better way to fix this, or
Make it work, even if it was suboptimal, and move on to other, more pressing tasks.

I must admit, I had that urge inside me to soldier on, to fully understand the problem, to arrive at an elegant solution. But, after a moment of reflection, I knew getting it perfect wouldn’t matter to our customers. They wouldn’t care about our build system. Heck, they probably wouldn’t even know we had one! To them, the end product, the customer experience, is what matters most. That’s how they will judge ⚖️ the product and the service.

There’s also another dimension to opting for “good enough” in the software world. Business requirements, libraries, frameworks – you name it – change rapidly and the software I write today might be obsolete tomorrow. Especially feedback from the customers can (and often should) make a huge impact on a product. In our case, the first iteration of the desktop UI served its purpose, but people told us they were a bit lost when just starting out. We quickly made a lot of changes based on the feedback, creating an entirely new experience for one of the core flows. And while we used off-the-shelf UI components and reused parts of the code we have already written, some had to be thrown away.

In my opinion it’s not worth spending too much time on things that will undoubtedly change. Sure, I still will go for maintainable (read: easy to change/swap), but I would rather focus on coming up with solutions that are optimal in the business context. I know it will pay dividends 💰 later on.

A few words on hiring

Try to postpone hiring for as long as possible. It’s also part of “starting small” and is an important mindset to have early on. It’s not about money and time, but first getting a firm understanding of the business beforehand. Once you’ve obtained enough knowledge and experience, hiring someone to take over your roles will be way easier and more efficient.

To give you some examples, we did all the design work ourselves, in some instances leaning on ready-to-use products, in others engaging our creative side (like for UI or promo video). We also considered finding someone to fully own the marketing side of the business, but opted to take care ourselves of things like content creation and promotion on social media. All in a quest to better understand what is actually needed for the business, long term.

Keep in mind, tough, that it depends on the skillset of the funding team. The broader the better, with few focuses that really stand out. We are lucky to have such depth in the founding team 🦾, despite a highly engineering background. It’s not all or nothing – when in a pinch, we can always ask friends for help or hire a contractor for a specific task.

Three takeaways

In a startup world (and life in general), time is a valuable currency. Choose a technology that lets your company or project move as fast as reasonably possible at each stage of product development.
Customers don’t care how a developer solved a problem on the software side. They want the product to solve their pain, be reliable and be easy to use.
When building a product (startup, side-business), try to build great software, but don’t shy away from using shortcuts where it makes sense, unless you plan to send people to space. There’s always plenty of other things to work on.

Feedback and questions are more than welcome, either in comments or on social media 🙂

Thanks a ton to Piotr Tomiak (@PiotrTomiak) and Jakub Tomanik (@jakub_tomanik) for reading drafts of this article.

Making notarization work on macOS for Electron apps built with Electron Builder

Krzysztof Tarnowski — Fri, 09 Jul 2021 12:45:12 +0000

I ❤️ building things and, when it comes to software, I’ve done that for quite a few platforms and in various programming languages over the years. Recently I’ve been developing a desktop app built with Electron and I must say the whole first-timer experience has been rather pleasing. One thing that required “a bit” of attention was the build process for different platforms (Windows, macOS) and part of it was the app notarization step on macOS. What on paper looked like a really easy thing to do, took me a couple of hours and a lot of detective work to get it right 🕵️‍♀️.

Below is a step by step guide on how to set up notarization on macOS when using Electron Builder (22.7.0) and Electron Notarize (1.0.0), including a complete workaround for an issue I’ve experienced that has to do with Apple Notarization Service. Hopefully, I will be able to help you out like a true superhero 🦸🏻‍♂️, so your time and effort can be devoted to other, more pressing matters 🦾.

A bit of context

Want the solution right away 🧐? Skip to the step by step guide.

Why even bother with notarization in the first place? Well, on macOS (and Windows for that matter) there are various security mechanisms built into the operating system to prevent malicious software from being installed and run on a machine. macOS and Windows both require installers and binaries to be cryptographically signed with a valid certificate. On macOS, however, there is an additional build-time notarization step that involves sending a compressed .app archive to Apple’s Notarization Service (ANS) for verification.

In most instances, the whole process is painless, but in my case, i.e. an Electron app with a lot of dependencies and third-party binaries, not so much 🤕. It turns out the ANS expects the ZIP archive of .app package to be compressed using the PKZIP 2.0 scheme, while the default zip utility, shipped with macOS and used by Electron Notarize, features version 3.0 of the generic ZIP algorithm. There are some notable differences between the two and to see what I mean, try manually signing .app, then compressing it using:

Command-line zip utility,
“Compress” option found in Finder,

And submitting it for notarization from the command line. The Finder-created archive will pass, while zip-one will fail.

The zipinfo command line tool reveals that:

Finder uses PKZIP 2.0 scheme, while zip version 3.0 of the generic ZIP algorithm.
Finder compresses all the files in .app as binaries, while “zip” treats files according to the content type (code as text, binaries as binaries).
Finder includes magical __MACOSX folders to embed macOS-specific attributes into the archive, especially for links to dynamic libraries (e.g. found in some Node modules).

One way of getting around the above issue is to use ditto instead of zip to create a compressed archive of an .app package. Ditto is a command line tool shipped with macOS for copying directories and creating/extracting archives. It uses the same scheme as Finder (PKZIP) and preserves metadata, thus making the output compatible with Apple’s service. The relevant options for executing ditto in this context, i.e. to mimic Finder’s behavior, are:

-c and -k to create a PKZIP-compressed archive,
—sequesterRsrc to preserve metadata (__MACOSX),
—keepParent to embed parent directory name source in the archive.

The complete invocation looks as follows:

ditto -c -k —sequesterRsrc —keepParent APP_NAME.app APP_NAME.app.zip

To apply this to Electron Builder’s notarization flow, you need to monkey patch Electron Notarize’s .app and make the compress step use “ditto”. This can be done via “afterSign” hook defined in the Electron Builder’s configuration file.

You can learn in an follow up essay why I chose this particular approach. Hope you love it!

Setting up macOS app notarization, including workaround

Before you start, you first need to properly configure code signing, as per the official documentation of Electron Builder and various guides¹. For completeness sake I’ve included here all the steps required for making the notarization to work based on my experience and excellent work by other developers¹.

Create an app-specific password to use with Apple notarization service. Preferably using your organization’s developer Apple ID.
Create an Entitlements .plist file specific to your Electron apps. In our case, the following did the trick (entitlements.mac.plist):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <!-- https://github.com/electron/electron-notarize#prerequisites -->
    <key>com.apple.security.cs.allow-jit</key>
    <true/>
    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
    <true/>
    <key>com.apple.security.cs.allow-dyld-environment-variables</key>
    <true/>
    <!-- https://github.com/electron-userland/electron-builder/issues/3940 -->
    <key>com.apple.security.cs.disable-library-validation</key>
    <true/>
  </dict>
</plist>

Set entitlements and entitlementInherit options for macOS build in Electron Builder’s configuration file to the .plist created in the previous step.
Create a notarize.js script to execute after Electron Builder signs the .app and its contents. Place the file in the build directory defined in Electron Builder’s configuration file.

const {notarize} = require("electron-notarize");

exports.default = async function notarizing(context) {
  const {electronPlatformName, appOutDir} = context;

  if (electronPlatformName !== "darwin") {
    return;
  }

  const appName = context.packager.appInfo.productFilename;

  return await notarize({
    appBundleId: process.env.APP_BUNDLE_ID,
    appPath: `${appOutDir}/${appName}.app`,
    appleId: process.env.APPLE_ID,
    appleIdPassword: process.env.APPLE_ID_PASSWORD,
  });
};

Add "afterSign": "./PATH_TO_NOTARIZE_JS_IN_BUILD_DIRECTORY” to Electron Builder’s configuration file.
Monkey patch Electron Notarize. The script should run before Electron Builder’s CLI command. In our case, since we’ve taken a very modular approach to general app architecture, the build scripts (TypeScript files) include a separate commons module, which is imported by Electron Notarize patcher. The .ts files can be executed using ts-node via

ts-node -O {\"module\":\"CommonJS\"} scripts/patch-electron-notarize.ts

The patcher itself does one thing only, that is, it replaces the following piece of the code in build/node_modules/electron-notarize/lib/index.js:

spawn('zip', ['-r', '-y', zipPath, path.basename(opts.appPath)]

with

spawn('ditto', ['-c', '-k', '--sequesterRsrc', '--keepParent', path.basename(opts.appPath), zipPath]

Our code for the commons (patcher-commons.ts):

import {promises as fsp} from "fs";

export type FileContentsTransformer = (content: string) => string;

export async function replaceFileContents(path: string, transformer: FileContentsTransformer) {
  let fh: fsp.FileHandle | null = null;
  let content: string = "";

  try {
    fh = await fsp.open(path, "r");

    if (fh) {
      content = (await fh.readFile()).toString();
    }
  } finally {
    if (fh) {
      await fh.close();
    }
  }

  try {
    fh = await fsp.open(path, "w");

    if (fh) {
      await fh.writeFile(transformer(content));
    }
  } finally {
    if (fh) {
      await fh.close();
    }
  }
}

and the patcher (patch-electron-notarize.ts):

import {FileContentsTransformer, replaceFileContents} from "./common";

const ELECTRON_NOTARIZE_INDEX_PATH = "build/node_modules/electron-notarize/lib/index.js";

async function main() {
  const transformer: FileContentsTransformer = (content: string) => {
    return content.replace(
        "spawn('zip', ['-r', '-y', zipPath, path.basename(opts.appPath)]",
        "spawn('ditto', ['-c', '-k', '--sequesterRsrc', '--keepParent', path.basename(opts.appPath), zipPath]"
    );
  };

  await replaceFileContents(ELECTRON_NOTARIZE_INDEX_PATH, transformer);
}

// noinspection JSIgnoredPromiseFromCall
main();

Set APPLE_ID and APPLE_ID_PASSWORD environment variables (the ones defined in Step 1) before running Electron Builder on your developer machine or in your CI environment. You can use Keychain on your local machine instead.

And that’s pretty much it. You can check out a simple, working example to see how to put this all together. Now you can spend the extra time on something you enjoy doing 🏖!

Three takeaways

When stuck, look for the root cause in the least expected places. In the case of my project, the compression step was the unexpected culprit.
Be stubborn when a particular feature or bugfix is essential to a product’s success. Here, the notarization was important and it took some time to get it right, but the end result is customers feeling safe when installing the software.
Sometimes “working” is good enough. I could develop a better solution, but that would take some precious time. I opted to focus on more pressing issues instead.

Feedback and questions are more than welcome, either in comments or on social media 🙂

Thanks a ton to Piotr Tomiak (@PiotrTomiak) and Jakub Tomanik (@jakub_tomanik) for reading drafts of this article.

References

Relevant sources: https://medium.com/@TwitterArchiveEraser/notarize-electron-apps-7a5f988406db.
GitHub Gists of the complete code.