Please join me as I write our obligatory new year blog post where we reminisce on what happened in the last year (and more). There are exciting things at the end you might not want to miss.

Rewrite

In July 2022, I shared my 6 hard-learned lessons for technical founders. The intro mentioned my decision to fully rewrite the Savoir API. For three months in the summer of 2022, I had the chance to welcome Savoir's first contractor hire. We outlined a roadmap for release and set our priorities. Turns out that a hacked together system written in two months more than a year before wasn't cutting it for release. Getting it released to production would have cost weeks of work for a framework/language I wasn't an expert in.

So I made the tough decision to move to something I know: Golang. I've been working as a Golang developer for more than half a decade, and I'm confident in my abilities to build stuff with it. I had many other possibilities in front of me, many of which played more to my interests than my strengths. I decided to focus on what would bring me the biggest velocity and confidence. I want to build this quickly, and I want to do it right this time.

To avoid the same release pitfalls I faced with the old Elixir version, I chose to move forward with the Encore framework. This was one of the best decisions I've made in a long time. I am biased as a contributor to the framework and this isn't an Encore blog post, so I won't go into too much detail. Instead, I want to share how valuable it is to not have to worry about compilation, release, or infra. Savoir is a small project and still in its unreleased stage. Playing to my strengths also means understanding where to invest my limited time. By being able to outsource everything release-related to a framework and focus on the features, I saved a huge amount of time and effort.

As I am writing this post, the rewrite has been complete for more than a month now. I've officially started building new features. All the core features I wanted to migrate have been migrated, and it's a lot more stable with many more tests. Testability was one big thing I couldn't get working right with the previous framework, it's now seamless. This means I can (again) focus on building features rather than worrying about testing, or lack thereof.

The rewrite started in earnest in December 2022, which means it took about a year to fully rewrite Savoir. A good achievement given my limited resources, but it still could have gone better. Let me know if you'd like a more in depth post on my lessons learned in the future!

Rebrand

If you've read our previous posts or been a reader for a few years, you might have noticed our blog and website got a makeover back in 2022. In fact, this makeover happened barely a few months after my post describing my journey to redesigning the website three times. After writing that blog post, I discussed the content with the contractor. I still wasn't satisfied with what I could achieve by myself. We had money saved up for some development help, and we ended up deciding to invest it into hiring a designer instead.

We posted a contract description, made our limited budget clear from the get go, and I started interviewing. Since we're fully bootstrapped, I think it's very important to let designers know how much we can pay them. The last thing I want to do is waste someone's time on a project that doesn't bring them enough. I prefer to reduce my expectations rather than ask someone to work more for less.

We interviewed with three designers/agencies and ended up working with Buenas Design. I cannot recommend them enough, they took my rough designs and ideas, then created something truly unique and incredible. Our main objective, given our limited budget, was to define a concrete visual identity and create a new brand logo. What they delivered was beyond what I could have ever imagined.

Rather than randomly generated colors that mostly match one another, we now have a well designed color palette with clear guidelines. Rather than a, on-the-nose, robot in a book logo, we now have a studious suricate. I'm still very proud of the logos and websites I designed, especially given I had to learn all those skills, but seeing what we ended up creating with the help of a design was the highlight of my year. We officially switched to the new brand on the 16th of January 2023 with the introduction of Savant, our new logo, mascot, and product name. Sadly this meant saying goodbye to SavBot, I'll never forget you.

At the same time, we fully redesigned our website. The new version has a better flow of information, but also switched to a video format for explaining how Savoir works. We've had great feedback on the video and we're hoping to expand on it in the future.

In my opinion, this was the best time to invest in this level of rebranding. Our logo still isn't that well known, and releasing with our old brand would have meant losing that window of opportunity. If you're in your pre-release stage for your product and are considering investing in a designer, I can wholeheartedly recommend the experience, it's worth it.

Release

This brings us to January 2024 and this post. Savant is fully deployed to our staging environment and we're preparing a "stealth" release to production. We've been using Savant for a few months internally and it has been a great experience, but also a learning opportunity as we realize (and fix) some of the drawbacks of old decisions.

Why a stealth production release, you may ask? One of the most difficult decisions I made for the rewrite was to not migrate the self-serve features of the Savoir API. At least not for the first release. We don't have the resources to commit to a high visibility release, and we can't afford to fail and be forgotten. I learned early that it can be better to release silently than have your loud release be ignored. You can only shout "RELEASE!!" so many times.

For that reason, we'll be working closely with beta testers to get them integrated with Savant. It should only take a couple of clicks, but that hands-on approach will allow us to focus on the features users want as we build our self-serve flow. Another learning opportunity to add to the list!

Savant is now open for beta registrations to anyone interested in working with us to bring it to life. We want to build it for real users, and we're ready to build features for you if you're ready to try Savant out. If that sounds like something you want to be a part of, please sign up on our website or directly from here.

What's next?

With our release readiness officialized, my next focus is on building Savant as the best product it can be. I will probably not be as active on our blogs as I once was, but I want to take this opportunity to post more content. To make this possible, I'll be writing about the things we learn while building Savoir. Please let me know in the comment below if there's anything you'd like me to write about next!

See you all in my next post.

If what we are building looks interesting to you, please check our features and register for exclusive beta access on our website at savoir.dev. Feel free to also send me a message at info@savoir.dev, I'll be glad to answer any questions you have or give you a preview.

Savoir is the french word for Knowledge, pronounced sɑvwɑɹ.

The original design wasn't great

Imposter syndrome being what it is, I can't help but continuously question my design abilities. It's a fine line between looking at something you made from an objective point of view and unconsciously viewing that same thing more negatively than it really is. I find that line tends to get blurry the more I start at something. In the process of reviewing my own work, I may find a few things that stand out now but don't matter in the long run. For example, did you know the Savoir logo's eyes are not exactly at the same distance from the center of the logo? One is a few millimeters more to the right than the other. I wouldn't fault anyone for not noticing it, I only did with the help of a ruler. It's one of those situations where I had to seriously question if I was looking at this objectively. Did this small mistake make me a bad logo designer?

The same thing goes for the Savoir landing page's design. The initial version, built back in 2020, wasn't ugly, but it wasn't great either. It suffered from a lack of consistency, poor contrast, a bad choice of words that made people think we were selling a newsletter, and a poorly positioned layout that made the site look unprofessional.

The first iteration of the Savoir landing page

The bad layout decision and the bad flow of information were the main reasons why I started thinking of a redesign as soon as the page was hosted on Netlify. The core issue was the centered text and logo in the hero banner, which was then followed by a zig-zag "how it works" section, and a grid based features section. A viewer's eyes would have to jump around a lot, which isn't great for readability. There also was no clear explanation of what the product is about without having to scroll to the later section, which isn't a great first impression. The flow issue is very apparent when you draw a line of the typical "user story".

I had to get started somewhere

It took me more than a year to finally tackle the challenge of improving this design. During this time, I researched and designed. I drew a lot with Inkscape, made quite a few personal websites, and I bookmarked a lot of design inspiration. I also did a lot of work on the product's branding. The first version was mostly built without direction. I found some cool inspiration online after a few minutes of searching and got started. I hadn't considered what personality I wanted or what mood the page should create. I took some basic Bulma components and built something in a few days.

Going back to the drawing board, I now had a much better idea of the kind of personality and mood I wanted to see on the landing page. First and foremost, it should put a bigger emphasis on the git and chat bot nature of the product at the top of the page, that shouldn’t require any scrolling. After searching for inspiration online, I stumbled upon a thread of GitHub pull request flows. I really liked them; they showed the product flow really well and screamed "Git", which was exactly the kind of mood I wanted the product to convey.

I took these images as inspiration and immediately started designing. I soon realized that even with years of using the tool, I never learned how to make a good looking curved line. They are not the easiest thing to do in HTML and I was convinced it would be easier to make in SVG, which I had to learn from scratch.

I strongly believe in failing forward. If I didn't have the ability to build this flow the first time, I would work on it until I got it right. After hours of work (yes, hours), I managed to build a custom pull request icon with some status checks. It wasn't great, but it taught me how to make nice looking curved lines and how to play with gradients. It was a good start. I also decided to draw it vertically instead of horizontally, to break away from the centered hero and instead follow the zig-zag pattern of the rest of the application.

Going too far in one direction

Armed with my new skills, I started sketching the exact flow I imagined in my head and began designing. The great thing about this kind of iterative process is how it enables experimentation. I had a slightly better flow and messaging in place on the website already, there was nothing wrong with trying something bigger. I had no idea if my ideas would work in practice. I had to apply them to find out.

I tried, it took me 5 hours too

I don't think I'll make the news by saying that this version went way too far in the GitHub flow direction. With some adjustments, it could definitely look good, but I simply didn't have the skills to make this look better (The chat boxes are especially bad). It also showed me that larger doesn't equal better, the entire image would need to be very big to show the information properly. This would create a lot of empty space in the left column. I could make it horizontal, but suddenly we're back to the flow issues from the first version.

Learning from my mistakes

As soon as she saw the SVG version of the flow, Wajma Mohseni asked me: "can we compress it?". I wasn't sure if this could be possible; could I convey the pull request flow without representing it as two branches? Should I stick with the top to bottom branch flow after all? I had a hard time wrapping my head around this, but I decided to trust the advice I got. This taught me two things: 1. the GitHub-like flow is a good idea and shows what the product does at a glance 2. I'm not making the best use of my time by sticking with Inkscape. Don't get me wrong, Inkscape is an amazing tool, but I am a developer. If I want something to look good, I should build it in HTML and CSS, not SVG. Back on the internet I went to search for inspiration.

A constant in all my blog posts is that I really like sketching things down when I design. It helps clear my mind and my inability to draw makes it very easy to focus on the information over the looks. So I did just that. I went to my white board, aligned my monitor so it would show my inspiration board, and started sketching until I hit something I liked. It took some time, but shifting my perspective and having good inspiration really made things click.

Crazy what you can do with 90 degrees turns

With this sketch in hand, I decided not to follow my previous instincts and went on CodeSandbox rather than Inkscape. It was time to use raw HTML and CSS (using React), and drop SVGs (At least for now). It went a lot smoother and, after some back and forth, I finally ended up with this.

For someone who wrote to play to your strengths, it sure did take some time to apply my own tips. Saying it went a lot smoother is an understatement. As a developer with a good amount of frontend development experience, working with web technologies allowed me to create something great very quickly, then iterate on it without hitting my own skill limit. I also had the knowledge required to fix my own mistakes, like only using the px unit for positioning (That really wasn’t responsive).

As to how I built this compressed flow, it uses a CSS grid and lots of relative positioning to generate the arrows, lines, circles, and other components. It was initially built with only absolute positioning, but that made it very hard to scale and be responsive. The grid works amazingly.

Conclusion

Something I learned from this whole process is that I am definitely getting better at designing. Would I have a shot if I applied to be a junior designer? Probably not. It also taught me a lot about my own limits and design process. As we're now starting to look around for help from a designer, it is the right time to reflect on this month-long process, and think about what matters and what I can do better.

Do you also have some design stories you'd like to share? I'd love to read them in the comment below.

If what we are building looks interesting to you, please check our features and register for exclusive beta access on our website at savoir.dev. Feel free to also send me a message at info@savoir.dev, I'll be glad to answer any questions you have or give you a preview.

Savoir is the french word for Knowledge, pronounced sɑvwɑɹ.

After weeks of struggle, I decided to aim for a rewrite. I was faced with a cobbled together infrastructure that came with high costs to host and update, plus high difficulty in scaling it. Elixir was a blast to work with and it taught me many lessons, but it is time to say goodbye. I'm very positive about the whole experience and I believe it is the right choice. At the end of the day, I am a technical founder. I want to write code, and I am sure I'm not the only founder who’s more hyped about their technical decisions than their business decisions.

Rather than dwell on the story, I decided to dedicate this post to sharing my lessons with the community. Here are 6 lessons, in no particular order, for technical founders like myself. Do you have any lessons or experiences you'd like to share? Drop them in the comments I'd love to read them!

1. Don't get too excited by tech

I am a Golang and JavaScript developer, with sprinkes other languages like PHP, Python, and C#. I had never used either the language or the framework, and they wouldn’t necessarily be the first choice for a frontend-less, Webhooks-powered chatbots. Not saying it can't do it, but Phoenix is amazing at powering interactive web applications and removing all those features is more work than keeping them. How did I end up choosing Phoenix and Elixir then?

I had completed a functional programming course a few months prior and I was hyped for writing functional code with anything other than Lisp. I was in the mood for learning a new language at the time and the only "project" I had in mind was Savoir. To tell you how deep I went in my search for a “new shiny tool to use”, the other languages I was considering were Zig and Crystal.

I was bored of the tech I was using everyday and decided to go with what hyped me at the time. I built a product I wanted to sell with a technology I barely knew and a stack I barely grasped. It could have worked out, but the result I ended up with teaches me I should have gone with "the boring choice". Of course a new startup project should be fun, but building something for others means having to make tough choices for the sake of your prospective users. Building a product is a balance between making decisions for you and making decisions for your users, and I focused far too much into the "me" camp.

2. Play to your strengths

Many "startup starting guides" or "startup in zero steps" guides recommend using no-code or zero setup frameworks to build your product. They recommend getting started as fast as possible, acquiring users, then thinking about the technical implications of your choices down the road. These are really good tips. In fact, I strongly recommend looking at frameworks like getzero to get started as fast as possible if you're a more technically oriented person. What most of these guides/frameworks omit is that you should probably already be proficient in the platform they recommend before you even start. Building an entire product on Bubble is more than possible, but in my case, I am a very technical person. My strength lies in building backends, APIs and DevOps workflows.

I think founders, especially solo founders like me, should focus on where they excel and use the tools that make them productive. I tried Bubble before settling on the rewrite, and as amazing as it is, it was clear that I would be faster building an entire backend from scratch in Golang than with Bubble. Creating a product alone is incredibly tough, creating it with technology that doesn’t make you productive, even more so. We have never had so many options for building products, making it harder to choose between all of them. My recommendation– choose what you know.

3. Build for your market

When people come to me for tips on where to start with their business projects, my first piece of advice is to do your market research. When I started, I underestimated the value of knowing my market: of knowing who I am selling my product to and what they might want. For technical founders especially, I think good market research is one of the most powerful tools you will have when building your product. I didn't have that, and I ended up building features that were of no interest to my market: I had poorly defined my "minimum viable product" and that led to feature bloat. For example, one "hidden" feature of Savoir is its ability to load the security report from a GitHub organization (where it lists security issues from dependencies in multiple repositories) and generate a documentation website from it. Definitely useful for many people, but when I compared it to recent market research, I realized it had no selling point. My prospective users wouldn't need it.

I often see articles recommending that founders "define their minimum viable product early". This rings very true in my case, even more so when I consider that I did define what "minimum" meant for Savoir. But I did it with faulty data, which led to a faulty definition. A product should be built for the market you will be selling to.

4. Don't plan like you're Spotify

The first thing I did when I started building Savoir was not to write code, but to plan my sprints with a tool called Codetree. I highly recommend them by the way, if you're looking for a good GitHub powered project management tool. I planned my entire feature set through epics, and I would break things down into smaller issues on a bi-weekly basis. I personally really like working in more structured environments. There's something with this level of tracking that makes me feel like I’m part of something. Except that my team at Savoir was just me, and it would be just me for two whole years. In addition to paying for a tool I simply didn't need, it took hours of my limited time to plan my work rather than execute it.

Was this a waste of time? Not completely, I have traces of everything I did and I can track the upcoming work very well given how well laid out my plan is. But it's also true that I didn't need epics, milestones, weekly reports of my throughput, multiple projects, alerts when things weren't being shipped – you name it. And that's only the surface of everything I was doing in my planning sessions. It's my personal belief that people should plan even when alone if that's what makes them productive, you should play to your strengths after all, but it's also important to remember where your project is. Savoir wasn't at a stage where this planning would be useful in any way, and it was my role to know that and act accordingly.

5. Know your limits

A constant in all these lessons is that I like doing research before jumping on a project. I read a lot of articles and guides on how to run a company as a solo founder. I participated in an accelerator program and reached out to many mentor groups in my area. All good things, but it also led to all those people telling me things like "learn visual design" and "use a CRM", or even "learn how to manage your company's finances yourself". I took these tips to heart and tried to do everything myself, and I see too many founders doing the same thing. We all have limits, and it's very likely that technical founders like me can't manage an entire business, design a landing page, run the business, and hire people by themselves while building their product.

It's important to know where your limits are. There's help everywhere, a lot of it free. Use it. If people recommend using a CRM, it’s because it's a very valuable tool to invest in early in order to track your deals. I also think it's not to force you to learn it all by yourself, but rather as a way to add the word to your vocabulary. Many CRMs also offer support and “courses” to get started in sales. In my case, I had to learn the hard way; if these tips were too hard to follow up on by myself, it was a good sign that I was reaching my limits.

6. Get help

This brings me to my last lesson. I strongly believe that a founder's job is not to work 80 hours a week in order to get their vision to market. Rather, I think a founder is someone with an idea and the ability to deliver it. Delivering it doesn't mean you have to do it all yourself, however. As a technical person, I had the chance to grow in an environment with a strong ownership culture. If I was in charge of a feature, I owned getting it out the door. Too often, I would take this to mean that my job was to do everything and get it shipped myself. Yet, ownership means you own getting it out, not necessarily doing it yourself. Your team is there to help you and, in the context of a new startup, your network is your team.

I always hear the phrase "your network is everything" when talking to other founders. It’s very true, but it's also true that you don't need to start with a strong network. Part of building a business is building that network. Like code, it can be built from scratch. Nothing happens in a vacuum and everyone has relied on others to get things done, even if they might not want to admit it. I learned the hard way how much harder it is to start without a network, but I also learned how many people are willing to help. I am a very introverted person and it took all I had to reach out to others, but once I did, I never looked back.

Conclusion

I sincerely hope these lessons from my own startup story will help you in your own project. Please share your own lessons in the comments below, but also comment if you have questions or if you disagree with mine. I'm looking forward to our discussions!

Also, be on the lookout for future posts on the rewrite. I’ll have many things to share.

If what we are building looks interesting to you, please check our features and register for exclusive beta access on our website at savoir.dev. Feel free to also send me a message at info@savoir.dev, I'll be glad to answer any questions you have or give you a preview.

Savoir is the french word for Knowledge, pronounced sɑvwɑɹ.

Why does this matter?

With products like Slack, it is clear that the investment to build and maintain a Slack application on your own cloud infrastructure is worth it, because their user base makes sure you’ll see the growth needed to justify the costs. Products like GitHub or Discord are in the same category; their integration platforms have been successful regardless of how many resources are needed to get one going. It's exactly why Savoir is a GitHub application and why we are considering creating a Slack application as well.

But what happens if you're a smaller product without that ability to ensure a return on investment? Using Savoir again as an example, we're a new company with a yet-to-be-successful product. For us, it is clear that integrations would be very valuable. What if we could give users ways to react to Webhooks that triggers changes in content, and even update that content programmatically? What if you could sync content tracked with Savoir on platforms like GitBook, Readme, or GraphCMS? We know we do not have the resources to compete with these platforms and it makes a lot more sense to focus on what makes us unique: code-level tracking of your documentation. Clearly, integrations are the way to go.

To build integrations prior to the Cloudflare post, we'd have two options: build the integrations individually ourselves (and hope we build it the way users want), or ask our users to take the cost of hosting their own custom integration without being able to promise them the growth they need to make their money back. Workers for platforms create a third choice: we give our users a way to create integrations, and we execute them. We can then focus on giving our users the best DX possible and they can focus on building an integration that matches their needs. It also still leaves the door open for our own integrations - we have the perfect opportunity to dogfood our own integration platform.

Functions for platforms

Long story short, we're very excited about the potential of workers for platforms. So excited, in fact, that I decided to try building a prototype clone based only on the information contained in the announcement blog post. With this long-winded introduction behind us, let's now go through the process of building that prototype and learning about Fission.io and Kubernetes in the process.

Workers for platforms are described as isolated and secure JavaScript environments where users can upload and execute JavaScript functions in a V8 environment. There is no Node.js - it runs in a pure JavaScript environment as if it was running in a browser, but without the DOM. This is not a Serverless Function in the sense that we have to answer to triggers like with a more traditional serverless environment (commonly implemented as express servers). Rather, Cloudflare gives us a set of functions we can use to listen to events and they'll execute the function whenever an event we listen to happens. Let's try building that.

I uploaded a working version of this project on GitHub, feel free to follow along with the code there if anything doesn't work as described in this post: https://github.com/Minivera/functions-for-platforms.

Prerequisites

After doing a lot of research, I ended up settling on the Fission.io framework to support this project. Fission is an open-source Serverless framework running in kubernetes. Think AWS Lambdas, but we are in control of every part of the infrastructure. Kubernetes gives us the power to define the environments the containers will be executed in, and any other resources they need. This gives us the control we need to be able to create our very own environment for executing arbitrary JavaScript through the V8 engine. Each function can be isolated as much as we need to and Fission is really great at giving us the ability to quickly create multiple environments.

Since Fission is built on Kubernetes, it will take care of a lot of the heavy lifting and allow us to focus on what we want. I'll make sure to explain everything I'm doing, but this post won't go into too much detail about Kubernetes. You will need Node.js installed on your machine. I recommend going with the most recent LTS version (version 16 at the time of writing this article).

To be able to use Fission, we first need to set up a kubernetes cluster. A cluster is the "cloud" environment where all the resources are created and managed. It's like your very own specialized GCP or AWS running only containers. I'll be using Minikube to manage a cluster locally in this post, as I've found it to be the most compatible with Fission. It is a great tool with lots of utilities, and it runs the entire cluster inside of another docker container, which makes it very easy to clean up. Let's get started with setting up Minikube on our machine.

1. First, Install docker, based on your OS. As said previously, Minikube runs the cluster inside of a Docker container. Docker and Kubernetes are very complementary tools, so Docker will likely be useful even if you're not using Minikube.
2. Install kubectl and helm to be able to manipulate a kubernetes cluster. kubectl is the official Kubernetes CLI tool and helm is a utility deployment tool for creating and deploying kubernetes applications. We will not be using helm directly in this post, it is a dependency of Fission.
3. Install the fission CLI, it will use kubectl and helm to set up Fission automatically for us.
4. Finally, Install Minikube.

Once everything is installed, start the Minikube cluster using the command minikube start in any terminal. Minikube will download a few docker images and start the cluster. Once completed, run eval $(minikube -p minikube docker-env) in the same terminal. This tells that terminal session to run any docker command inside the Minikube cluster, allowing us to do things like pushing or pulling images inside of the cluster. Without this command, we wouldn't be able to use our custom V8 image locally, as the cluster cannot access our local docker registry (It runs inside a container). Note that this command only works for the current terminal session, if you close that terminal, you'll have to run it again.

The final step is to install Fission itself on our new cluster. There are a few ways to install Fission, we'll be using helm and installing it on Minikube. Run the command below -- copied from the official docs -- to get Fission installed and ready to start.

export FISSION_NAMESPACE="fission"
kubectl create namespace $FISSION_NAMESPACE
kubectl create -k "github.com/fission/fission/crds/v1?ref=v1.16.0"
helm repo add fission-charts https://fission.github.io/fission-charts/
helm repo update
helm install --version v1.16.0 --namespace $FISSION_NAMESPACE fission \
  --set serviceType=NodePort,routerServiceType=NodePort \
  fission-charts/fission-all

We're now ready to get started!

Uploading functions

One important thing I noted from the Cloudflare blog post is how important speed is to their implementation. It's clear they wanted their integrations to be as fast as any other worker function running on their platform. We won't get into running this project at the edge or avoiding performance loss from Fission, but we do want to do as much as possible to improve performance.

For this reason, we'll be using a network disk over something like a CDN for uploading the JavaScript files. Executing these files will only require a direct file system access, which should be much faster than having to do the round trip to some CDN server. We'll be using YAML specification files to manage our infrastructure and applying them with kubectl. While we could only use the CLI command, I find that specification files are much more expressive and configurable. Looking at the official Kubernetes docs, we find a special kind of resource called a "persistent volume". A persistent volume is like a docker volume, but the files created in that volume are persistent rather than ephemeral. With Fission, our containers will be started and stopped constantly, so this persistent volume is a great way to share files between the containers.

Since the only thing we need from Kubernetes is to manage this volume, we'll keep the specification files simple. Create a new directory called kubernetes and then create a file named code-volume.yaml in that directory. Copy this YAML into that file.

# kubernetes/code-volume.yaml
apiVersion: v1
kind: PersistentVolume
metadata:
  name: code-volume
  namespace: fission-function
spec:
  storageClassName: manual
  accessModes:
    - ReadWriteOnce
  capacity:
    storage: 5Gi
  hostPath:
    path: /data/code-volume/
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: code-volume-claim
  namespace: fission-function
spec:
  storageClassName: manual
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 3Gi

This YAML specification file defines the volume itself - called code-volume - directly in the kubernetes namespace for the Fission functions containers. In short, namespaces allow us to isolate parts of the cluster for easier management, and Fission uses them a lot. We want our volume to be as close as possible to where the functions will be executed (since we'll have to connect this disk to the containers used by the function), that's why we create it directly in that namespace. It's a very small disk at 5 Gigabytes, but that's enough for testing things out.

The second element created is a persistent volume claim named code-volume-claim. Individual containers use this claim to request access to the persistent volume and it allows us to define the base permissions and access. A persistent volume, in Kubernetes, is a resource in the cluster. A persistent volume claim consumes that resource and defines its access. In our case, we're telling Kubernetes to give us access to 3 Gigabyte out of the 5 available in read-write mode, and that only one node can read or write at a time through the ReadWriteOnce access mode. In a real-world situation, these constraints would likely lead to access locks and prevent concurrent access. This is fine for a prototype, but we'd have to manage access properly if we were to deploy this in production.

Let's create these resources now. Run the command kubectl apply -f ./kubernetes/code-volume.yaml in your terminal. This will tell kubectl to take the specification file we just created and apply its content on our cluster. If we ever change this file, running the same command will update the cluster by applying any changed properties without recreating everything. Pretty useful.

Specification files like these are very useful and make the commands much easier to run, since we don't have to hope for the best with command arguments. Fission also supports specification files; any Fission CLI command can be appended with --spec to create a specification file in the specs directory. We can then run fission spec apply --wait to apply the specification files on the cluster like we would with kubectl.

For the rest of this blog post, we'll be using Fission specification files over command lines as it will make things a lot easier for us. Let's start by creating the spec folder itself. Run the command fission spec init to initialize that folder, Fission will add a few files in there. We can now start creating the environment and the function for uploading scripts. Create a env-nodejs.yaml file in this directory, copy this YAML into that new file.

# specs/env-nodejs.yaml
apiVersion: fission.io/v1
kind: Environment
metadata:
  creationTimestamp: null
  name: nodejs
  namespace: default
spec:
  builder:
    command: build
    container:
      name: ""
      resources: {}
    image: fission/node-builder
  imagepullsecret: ""
  keeparchive: false
  poolsize: 3
  resources: {}
  runtime:
    image: fission/node-env
    podspec:
      containers:
        - name: nodejs
          image: fission/node-env:latest
          volumeMounts:
            - name: code-volume
              mountPath: /etc/code
      volumes:
        - name: code-volume
          persistentVolumeClaim:
            claimName: code-volume-claim
  version: 2

This YAML defines a Node.js environment. In fission, environments are the definition for the containers where each function will be executed. The containers run in a unit called a pod, Fission will create an arbitrary number of pods and scale them based on demand. You can see pods as like docker-compose files that run a few containers with shared resources. All pods run in a node, which is like a virtual machine with a bunch of docker-compose files (the pods) running on it. Fission will take care of creating the pods and will balance requests on all the pods automatically.

This file was created by running the command fission environment create --name nodejs --image fission/node-env --spec, with a few modifications. We're giving the name nodejs to our environment in line 6, then we tell Fission to use the official Node.js image in line 14 to build the container and the official Node.js runtime image for the function in line 20. Finally, we define a custom podspec object in line 21 where we mount our persistent volume as a docker volume, meaning each container will now have a directory named /etc/code where they can access the content of the persistent volume. podspec is a very powerful tool that gives us the ability to configure the containers in the pod. We could, for example, add a second container running redis if we ever needed an ephemeral redis database.

We'll be using Node.js to upload code to our persistent volume. Fission supports complete NPM projects with modules, but our code only needs the base Node.js modules, so we'll keep things simple by creating a single script. Create a src directory and add a function-upload.js file in that directory, copy the following code in there.

// src/function-upload.js
const { promises } = require('fs');
const path = require('path');

// Path to the persistent volume
const diskPath = `/etc/code`;

// Function to hash a string into a short string.
const hashContent = (content) => {
    let hash = 0;
    if (content.length === 0) {
        return hash;
    }

    let chr;
    for (let i = 0; i < content.length; i++) {
        chr = content.charCodeAt(i);
        hash = (hash << 5) - hash + chr;
        hash |= 0;
    }

    return hash;
};

// Fission will execute the function we export in the Node.js environment. 
// Content contains things like the body and headers
module.exports = async function (context) {
    // This function expects a raw body (no JSON) for uploading a JavaScript script
    const fileContent = context.request.body;

    console.log(`Received function "${fileContent}", hashing.`);
    // Create a file name based on the file content. We hash that content so 
    // the same content will always have the same name.
    const fileHash = hashContent(fileContent);

    console.log(`Writing file ${fileHash}.js to the persistent volume`);
    // Write the file content onto the persistent volume.
    await promises.writeFile(path.join(diskPath, `${fileHash}.js`), fileContent);

    return {
        status: 200,
        body: {
            message: 'function successfully uploaded',
            // We return the filename so we can execute it later
            id: fileHash,
        },
    };
}

This function defines the base API code for uploading a script. We receive that script as the raw string body of a POST call, then hash that content to generate a unique file name. Finally, we create a file on the persistent volume to host that file and return the hashed name for executing that function in our V8 function.

Run fission function create --name function-upload --env nodejs --code src/function-upload.js --spec to create the function spec followed by fission httptrigger create --url /upload --method POST --name upload-js --function function-upload --spec to create the HTTP trigger spec. Run fission spec apply --wait to apply the newly created spec files onto the cluster.

In Fission, a function is the definition for executing code in an environment. In this case, we tell Fission to run our code for uploading scripts inside the Node.js environment. A trigger is what causes a function to execute. There are multiple trigger types in Fission, but since this is an API, we'll be using HTTP triggers. This tells Fission to run the function whenever an HTTP call is sent to the URL specified, /upload in our case.

Feel free to test the function execution with curl. To do so, export the Fission router URL (the entrypoint to call HTTP triggers) as an environment variable in your terminal with this command

export FISSION_ROUTER=$(minikube ip):$(kubectl -n fission get svc router -o jsonpath='{...nodePort}')

In the same terminal, try running this command to send a POST request to our upload function. This should execute and return a JSON payload with the file id.

curl -XPOST "http://$FISSION_ROUTER/upload" -H "Content-Type: text/plain" -d 'console.log("Hello, World!")'

In MacOS or Windows environments, you may need a load balancer. Check the official docs from Minikube to set it up. The repository for the project has the kubernetes specification file ready in the kubernetes folder if needed.

Executing functions

Now that we have everything ready to upload code, we need a way to execute that code in a secure V8 environment. The Cloudflare blog post is clear that V8 was the key to unlocking a secure and isolated environment, so we'll be following in their footsteps. This means we can't use the default Node.js environment from Fission, we'll have to build our own. Thankfully, Fission has a binary environment we can partially reuse for this.

To build our own environment, we need to create a container image to use as the runtime. Fission also has a concept of builders, images that build environments based on the code given (For example, the Node.js environment will install dependencies defined in a package.json file). We only need to define our own runtime, we can reuse the binary builder since we'll be using a bash file as our function script. Let's start from the base binary image and change the Dockerfile to add V8 in that image.

Download the content of this folder in the official Fission environment repository: https://github.com/fission/environments/tree/master/binary and copy the two .go files and the Dockerfile into a newly created image directory. Open the Dockerfile and replace its content with this code:

# image/Dockerfile
# First stage, to copy v8 into the cache. V8 is built for Debian
FROM andreburgaud/d8 as v8

RUN ls /v8

# Second stage, build the Fission server for Debian
FROM golang:buster as build

WORKDIR /binary
COPY *.go /binary/

RUN go mod init github.com/fission/environments/binary
RUN go mod tidy

RUN go build -o server .

# Third stage, copy everything into a slim Debian image
FROM debian:stable-slim

RUN mkdir /v8

COPY --from=v8 /v8/* /v8

WORKDIR /app

RUN apt-get update -y && \
    apt-get install coreutils binutils findutils grep -y && \
    apt-get clean

COPY --from=build /binary/server /app/server

EXPOSE 8888
ENTRYPOINT ["./server"]

This Dockerfile has three stages. First, we download and test an image found on the Docker registry called andreburgaud/d8. This image has V8 prebuilt for Debian (You might need to build V8 on MacOS) so we can save the few hours it takes to build it. In the second stage, we copy the official .go files from the Fission binary environment and build them for Debian. These go files create a server that takes in commands from the triggers and executes a binary file in response, that’s how Fission supports any binary. Finally, the third stage puts everything together by setting up the container as defined in the original binary Dockerfile and copying V8 to a specific directory so it's available.

Run the command docker build --no-cache --tag=functions/v8-env . in the same terminal where you previously ran eval $(minikube -p minikube docker-env). This will build the image and tag it under functions/v8-env inside the Minikube cluster, so Fission can access it.

Time to create our environment! Go to the specs directory again and create a env-v8.yaml file. Copy this YAML into it.

# specs/env-v8.yaml
apiVersion: fission.io/v1
kind: Environment
metadata:
  creationTimestamp: null
  name: v8
  namespace: default
spec:
  builder:
    command: build
    container:
      name: ""
      resources: {}
    image: fission/binary-builder:latest
  imagepullsecret: ""
  keeparchive: false
  poolsize: 3
  resources: {}
  runtime:
    image: functions/v8-env:latest
    podspec:
      containers:
        - name: v8
          image: functions/v8-env:latest
          volumeMounts:
            - name: code-volume
              mountPath: /etc/code
              readOnly: true
      volumes:
        - name: code-volume
          persistentVolumeClaim:
            claimName: code-volume-claim
  version: 2

This environment is very similar to the Node.js environment, except we use the fission/binary-builder official image from Fission to build the container and our custom functions/v8-env for the container runtime. Like with the Node.js environment, we also connect the persistent volume, but in readOnly mode this time. We don't want our users to be able to write things to the volume from their own scripts.

Next, go to the src directory and create a function.sh file. Copy this code into that new file.

# src/function.sh
#!/bin/sh

file_id="$(/bin/cat -)"

printf "executing /etc/code/%s.js with /v8/d8\n\n" "$file_id"
printf "output is: \n"

 # This will not print errors but instead causes the process to crash, for now
/v8/d8 "/etc/code/$file_id.js"

When the go server from the official Fission binary environment runs a script or binary, it provides the request body in the standard input stream (accessible by reading from it with /bin/cat -). To avoid having to parse JSON or headers, we'll take the file name from the previous upload function as the raw body and execute the JS file from the persistent volume in V8 directly.

Let's create the function and trigger now. Run fission function create --name run-js --env v8 --code src/function.sh --spec followed by fission httptrigger create --url /execute --method POST --name run-isolated --function run-js --spec to create the two spec files. Run fission spec apply --wait to apply the newly created spec files onto the cluster.

We now have a function that can load a JS script uploaded through our Node.js function and execute it in an isolated and controllable V8 environment. We can control how many resources the function has through the environment specification file, but also how much time it is allowed to run. We have total control over how much power we give our users thanks to Fission and Kubernetes.

Testing the functions

The final stage is to test what we just built! If you haven't done so already, export the Fission router URL as an environment variable in your terminal with this command.

export FISSION_ROUTER=$(minikube ip):$(kubectl -n fission get svc router -o jsonpath='{...nodePort}')

In the same terminal where you exported the router URL, run this command to send a POST request to the upload function. It should return a JSON payload with the file id under the id property.

curl -XPOST "http://$FISSION_ROUTER/upload" -H "Content-Type: text/plain" -d 'console.log("Hello, World!")'

Copy the ID and run curl -XPOST -k -d "<ID>" "http://$FISSION_ROUTER/execute", replacing <ID> with it. You should see the words Hello, World! appear in your terminal. That means it worked!

What happened here exactly? When you sent the first request, the Fission router sent it to our upload function running in a Node.js container, which then creates that file in our persistent volume. The second request is then routed to our execution function running in our custom V8 containers, which loads the same file based on its file id from the volume and runs it, printing the result to the standard output. The Fission binary env is set up in such a way that any output is sent back as the result of the HTTP call.

Feel free to test this with more complex code, the code should print whatever you ask it to log. The next step for this prototype would be to provide environment variables and functions to our users so they can react to events triggered by our system, but that will be for another day!

Where to go from here?

In this post, we built a prototype for cloning the workers for platforms product from Cloudflare. Our implementation shows some promise, but it is also very limited and flawed. Due to the selection of frameworks and technologies, and also to the nature of this project which is based entirely on a single blog post, this prototype has a few flaws worth talking about.

First, anyone can technically access anyone else's scripts. A user could potentially write a script that loops through all the files in the persistent volume and prints the code of each file, potentially leaking any secrets saved directly in there (even without Node.js' fs module). We'll have to make sure each function can only see its script and nothing else.

The next issue is access. At the moment, anyone can access the two endpoints and do pretty much anything they want if we were to deploy it to the cloud. The first step towards deploying this is to make sure these two endpoints are only accessible to other internal services and secured. We'd have to create a separate service to route requests to our Fission cluster or something similar to abstract the implementation.

Finally, there is the issue of performance. This prototype isn't configured to run at the edge, but it also has some performance issues that would need to be improved to satisfy the requirements outlined in the Cloudflare blog post. The serverless nature of this project means we'll have to deal with cold starts and limited resources in our kubernetes clusters.

These optimizations are far beyond the scope of this first post, but maybe we can continue exploring in a future post! In any case, I hope you enjoyed this long post and I'm very much looking forward to seeing where the community takes workers-for-platforms.

Please check out the repository where I uploaded a working version of the prototype here: https://github.com/Minivera/functions-for-platforms. Contributions are welcome.

I'd love to hear your thoughts - please comment, share and follow.

We are building up Savoir, so keep an eye out for features and updates on our website at savoir.dev. If you'd like to subscribe for updates or beta testing, send me a message at info@savoir.dev!

Savoir is the french word for Knowledge, pronounced sɑvwɑɹ.

These questions came back to haunt me as I was designing the GraphQL API to power the Savoir dashboard (But also other clients in the future). I ended up going for a domain and consumer-oriented approach which I think works really well for dashboard-type applications. I want to share the story of how I designed this API and the lessons I learned. Hopefully, it may be useful for your own future projects.

Define the consumer needs first

Savoir is a GitHub application for tracking the code's documentation status, it fetches data from GitHub and associates that data to documentation content created by users. Commits and status checks are associated with content and activity entries. I knew the API should surface that data somehow, but not to which extent. It was very likely that a status check's annotation was not a field I would end up needing for this dashboard, in the same way that users owning organizations rather than the other way around is not a pattern I'd need to surface. The first thing I needed to define was "what data will this dashboard need?".

One of our core values at Savoir is "integrated". We designed our application to be as integrated as possible within GitHub. Our dashboard shouldn't be yet another way to write content. Instead, it should be a hub for everything outside the core experience of writing and tracking your documentation within GitHub, things like billing or a repository's settings. It should allow our users to know, at a glance, the status of their documentation and make decisions on where they have to increase or adjust their documentation efforts. The real product design process was far more in-depth than this, but this gives you a good idea of the product direction I wanted to take.

Knowing this, it became clear what this dashboard needed: access to the logged-in user data; access to GitHub organizations, their repositories, and the repository's settings; a way to edit content; and a way to track all the status checks handled by Savoir. All this data is hidden behind a user's permissions, and you wouldn't want your repository's settings to be visible to other users.

Nested schema over a flat structure

Whenever I design a GraphQL API, I tend to fall into the trap of designing that API with REST endpoints in mind. For example, for this dashboard, my first reflex was to start designing a schema like this.

# Simplified schema

type User {
    # An authenticated user's data
}

type Organization {
    # A GitHub Organization

    "A repository owned by this organization"
    repository(name: String!): Repository
}

type Repository {
    # A GitHub Repository
}

type Content {
    # A content page for a documentation website
}

type Query {
    user(): User
    organization(id: ID!): Organization
    content(path: String!): Content
}

As said earlier, all access to the dashboard is restricted behind a login. Since we don't want this API to allow us to fetch data a user doesn't have access to, we assign the authentication token to every query. At this point, I am pretty much creating a type REST API, which has its benefits, but also a few major drawbacks. The biggest drawback of this type of schema is that we'll need to fetch the user's data for every query. If you request an organization, the API needs to check if the user authenticated with the token has access to that organization.

The main outlier here is the repository query, which is nested as a field in the organization. I could have made it a query as well, but I would then have needed to take an organization's ID as well to make sure the API doesn't accidentally fetch the wrong repository by name. It seemed silly to have that second parameter in a root query when the parent organization implicitly provides it.

By nesting the repository into the organization, it implies that the organization owns all its repositories, they cannot be fetched without first fetching the organization. Similarly, this implies that a repository cannot exist outside of an organization. To fetch a repository, the server needs to first resolve the organization. In REST, that would be represented by a domain, like /org/:id/repo/:name.

This "natural" ownership pattern came as a result of that clear relationship between the two, but also from a desire to reduce the number of parameters on a query. Looking at the schema more, there seems to be a "hidden" parameter in the user authentication token. If not using authentication headers, I could almost rewrite the query schema like this.

type Query {
    user(authToken: String!): User
    organization(authToken: String!, id: ID!): Organization
    content(authToken: String!, path: String!): Content
}

This tells me there is a clear relationship between users and every other type. I only want to allow a user to access organizations or content pages they have access to, and to do this I need to authenticate every request. Taking into account what we just learned with repositories, it shows we can solve the drawbacks outlined earlier by having the user own those fields rather than have them as queries. Rewriting this schema with that in mind, we come to this:

# Simplified schema

type User {
    # An authenticated user's data

    "Fetch an organization owned or accessible by this user"
    organization(id: ID!): Organization

    "Fetch content owned or accessible by this user"
    content(path: String!): Content
}

type Organization {
    # A GitHub Organization

    "A repository owned by this organization"
    repository(name: String!): Repository
}

type Repository {
    # A GitHub Repository
}

type Content {
    # A content page for a documentation website
}

type Query {
    user(): User
}

We now have a single query that needs authentication, and once authenticated, we can reuse the auth context to fetch organizations and the content that the user has access to. In fact, the real Savoir API only has a single root query, the user() query. Every other field is owned by other types; the tree gets pretty complex. To fetch a status check, for example, I have to write a query that fetches the user, organization, repository, commit, and finally the status check.

This may look intense. Why design every root query as a nested field like this? What if I am fetching a pull request by number? Do I really need to get the organization in that chain? It all comes down to reusing context in my opinion. One problem I glossed over earlier was how complex it can be to check for permissions in a flat API design. How do I know the repository I am fetching can be accessed by the user? I need to validate that the user has access to the organization owning the repository in addition to the repository itself.

In a nested context, it's not something we have to worry about. Simply told, if I fetch a repository from an organization, I know that organization was accessed through the user query and thus that organization can be viewed by the user. I can then only validate admin access to that repository as permissions can be very granular in GitHub, without worrying about the permissions on the organization itself.

To go back to our earlier example, when fetching a status check through a field on a commit, I do not have to check for access to that status check. I know from the context that the user has access to the commit because it's owned by a repository the user can access. In the context of a dashboard where we definitely don't want to accidentally leak status checks to other users, that guarantee makes things a lot simpler.

The guarantee extends to other checks like existence. When fetching a repository by ID, I do not need to check if the organization it is owned by still exists in GitHub. That was already checked in the parent's resolve. While the nested nature of the schema may add complexity to individual queries, it made the overall backend logic a lot simpler and gave a clear separation of concerns to every resolver.

Paginate everything

Another thing I glossed over was fetching lists of elements and pagination. That is because I initially glossed over it when I was originally designing the API. I couldn't decide which criteria to use to decide if I should paginate a list or not. Pagination can make queries a lot more complex (not to mention how painful they can be in TypeScript). Consider this schema, using relay pagination:

# Simplified schema

type Repository {
    # A GitHub Repository
}

type RepositoryEdge {
    cursor: String
    node: Repository
}

type RepositoryConnection {
    edges: [RepositoryEdge]
    pageInfo: PageInfo!
}

type User {
    # An authenticated user's data

    "Fetch all repositories owned or accessible by this user"
    repositories(): RepositoryConnection
}

type Query {
    user(): User
}

To query all the repositories for a user, the query would have to look something like this, with the $after parameter used to fetch the next page if any.

query Repositories($after: String) {
    user {
      repositories(first: 20, after: $after) {
        edges {
          node {
            ..
          }
        }
        pageInfo {
          hasNextPage
          endCursor
        }
      }
    }
  }

Accessing those repositories in JavaScript gets quite long (user.repositories.edges.map(edge => edge.node). What happens if I want to loop over all the commits of all the repositories? Our API already follows a deeply nested structure. Adding connections to all lists makes each query massive. Whether to paginate a query or not is a reasonable question to have: is it worth investing in paginating a list that may have, on average, 20 elements?

To answer this question, I ended up relying on the wisdom of the Lead Backend Engineer from a few roles back. Whenever we asked if we should paginate or not, they always said "If you're thinking about not paginating a list, then paginate it". Translation: always paginate. In the context of a dashboard specifically, we want things to be responsive and reactive. Unless we know for certain that a list will only have 10 elements and remain unchanged, then a list should be paginated.

I think it is also worth considering this kind of question from the perspective of the product. A dashboard is a product, it's accessed by users to give them all the information they need to make good decisions about usage of the product. Going back to the definition I outlined for the dashboard, to be a successful product, it's clear that pagination should be the standard. In the case of Savoir, the dashboard should be quick to load and mostly needs to give the user access to specific pieces of information. We do not have complex charts with thousands of data points (which could still be paginated based on the selected time frame). In short, the UX required for a pagination field to work is more than acceptable.

In the past, I often questioned the wisdom of my former colleague, but having designed this product and the API to power it, I now understand where they were coming from. Should you be as intense as they suggested? I think it depends on your specific product needs. In the case of the Savoir dashboard, the answer was yes.

Onto today

The Savoir dashboard is still being built as I write these lines, but these few lessons still guide the entire architecture and design of the API. What are the lessons we learned in this article? Here is a short summary:

• Define who consumes an API early. Knowing the target audience of an API helps drive decisions and define the problem statement the API is for.
• Do not mirror the data or permission model in your GraphQL schema. The schema should represent the data the product needs and not the other way around.
• GraphQL works best when types are nested based on ownership. Nest queries within other types to reuse their context and simplify the backend logic.
• Always paginate, unless a list is strictly limited in size or your product demands unpaginated list fields.

This post ended up being much more of a story than a tutorial, contrary to what I initially planned. Yet, I think these lessons might be useful in your design and decision-making process for your GraphQL-powered dashboard. Please comment below or drop me a line to share your experience.

Stay tuned for the next part of this series where I'll provide an update on how we implemented mutations and when to combine both GraphQL and REST to power a single application. For those looking for a tutorial, we will also be releasing a post on GraphQL API documentation in the near future.

I'd love to hear your thoughts - please comment, share and follow.

We are building up Savoir, so keep an eye out for features and updates on our website at savoir.dev. If you'd like to subscribe for updates or beta testing, send me a message at info@savoir.dev!

Savoir is the french word for Knowledge, pronounced sɑvwɑɹ.