The JavaScript Journal

Launching a Remix app with Postgres using Prisma

2024年06月25日T00:00:00+00:00

We’re Fly.io and we make it easy for developers to do hard things without breaking a sweat, like deploying applications close to your users and scaling to exactly what you need in the blink of an eye. Or, in the case of this article, launching applications with Postgres with incredible simplicity.

In 2021, we launched Fly Postgres to resounding fanfare - seriously, we'e still cheering about it to this day. For folks who need a straightforward, familiar database storage solution and aren’t too pressed about managing it themselves, it’s an incredible and flexible storage option. In addition, launching an application on Fly with Postgres is so simple that it kind of feels like magic.

Launching a new app with Postgres is trivial. I’m not even exaggerating, and to prove it we’ll be walking you through the process of launching a basic Remix app on Fly that you can follow along with.

This demo is meant to be a starting point for folks who are new to using Fly Postgres. You can use it as a playground for experimentation, whether you’re familiar with Postgres but want a low-stakes, simple example to tool around with directly or are new to Postgres and/or relational databases as a whole. Feel free to turn the code completely upside down.

The three primary steps we’ll go through are:

Launch our app
Tweak our database settings
Deploy changes

We can also use the DATABASE_URL environment variable directly within our code as soon as Postgres is up and running without any extra work, as it’s automatically configured as a secret during provisioning.

Okay, so what does this look like in action?

Want to experience this process but don’t have anything you can actively test with? No problem! We created a simple Remix app which you can find in this repository.

Picture this: Your best friend’s birthday is coming up and you want to gather ‘happy birthday’ messages from their friends and family as a surprise. So, you’ve created a simple online guestbook with Remix and have decided to use Postgres, leveraging the Prisma ORM, to store those messages.

Clone the repository linked above, navigate to the directory in your terminal, and get ready to follow along with us.

Our Application

First, I’ll provide a little foundational information about the project that should help you as you’re looking through the files. The structure itself is simple:

Our guestbook itself only uses a single page (fancied up with TailwindCSS), so the only route we’re concerned with is _index.tsx. The header of this page explains its purpose: to allow folks to post messages for our bestie’s birthday. In our <main> element, we’ve imported two components via our index route: NewMessage.tsx (a form that writes submitted messages to our database) and MessageList.tsx (a section of code that displays submitted messages on the page).

We make use of Prisma in this application - an incredibly robust open-source ORM that simplifies the process of building projects with databases. In our demo app, we’ve used it to inform the overall structure (essentially, what fields will house what kind of data and in what way and/or capacity) of the data we’ll be storing in our database by creating a model in a Prisma schema, which you can find in /prisma/schema.prisma.

In our case, we only need one table in our database so we only have one model in our schema. We’ve named that table visitors and it contains fields for id (we use this to number our messages), a createdAt timestamp, name, email, message title, and message content.

Step 1: Flyctl

Everything begins with flyctl, the command-line interface for Fly.io. You’ll want to install it as a first step. Then, we’ll kick things off with the Fly Launch command:

fly launch

This creates a Dockerfile, a fly.toml config file, and any other platform resources necessary to get your app up and running on a Machine. Flyctl is clever enough to recognize we’ve used Prisma in our application, and so it understand it should set up Fly Postgres for us by default.

If you want to tweak those settings, you can select y when prompted to be taken to the web interface where you can customize the name and configuration settlings for your database. Otherwise, we can select n to proceed with the settings that have been selected for us. With your settings confirmed, two apps will be created: one for your app and one for Postgres.

Flyctl will handle provisioning and completing the first deployment of your application all in one fell swoop, so maybe enjoy a snack while it does its thing - but maybe a small one. It won’t take as long as you think.

Thanks to Prisma and flyctl, all the heavy lifting has been done for us. During the development process, we declared a DATABASE_URL in our .env file in order to connect to our Postgres database. However, since we’ve already created our database schema with Prisma, Fly has everything it needs to move forward with building the database and configuring the DATABASE_URL as a secret for us.

Flyctl will move forward with building your Fly App and getting it up and running, including running your database migration and building your table from the prisma schema. Once complete, the CLI will share a link to your new app, So, why not go add a message?

Step 2: Celebrate

Only two steps? Yep! Only two. Your application and its associated database are up and running and you didn’t even break a sweat.

Moving forward, you’ll rely on the fly deploy command when deploying changes to your app.

But what if I want managed Postgres?

It’s true Fly Postgres is unmanaged. If you’re not comfortable with managing things like scaling for memory and storage or outage recovery yourself, then there are definitely managed database providers out there that can serve as great solutions like Supabase.

The process of launching a Remix app using Supabase as a managed Postgres provider only involves a couple added steps, especially if you continue to use Prisma as your ORM to streamline things. We have detailed guidance for using Supabase on our infrastructure but, simplified, the steps look like this:

Run the fly launch command. Select y to tweak your options and set the database to none instead of using Fly Postgres.
Run the fly ext supabase create command. This will initiate Supabase by creating an account associated with your Fly.io account, set up your db, and set the environment variables for interfacing with it.
The command line will return a DATABASE_URL and DATABASE_POOLER_URL. We use the DATABASE_URL for this project. You’ll want to set it as a secret in your app by using the fly secrets set command like this: cmd fly secrets set DATABASE_URL=postgres://example.com/mydb
Celebrate!

Using WebSockets with Next.js on Fly.io

2024年06月05日T00:00:00+00:00

We’re Fly.io. We make hard things easy, including deploying your apps around the world, close to your users. This article illustrates how to use WebSockets in your Next.js app without the need for third-party services. If you’d like to learn more about deploying Next.js apps on Fly.io, check out our docs here.

In this article I’ll show you how to build a real-time chat app with WebSocket in a Next.js app. This solution works whether you’re using the App Router or the Pages Router, as much of the magic comes from setting up a custom Next.js server. Let’s dive in!

Demystifying WebSockets

To understand WebSockets, we should first compare them with something we’re more familiar with: HTTP requests. In an HTTP request, a message is sent to the server. The server Does A Thing, and then sends back a response. Once the request-response cycle has been complete, the connection is closed. This is an oversimplifictation, but the pattern of request followed by a response is the key point.

WebSockets work a bit differently, because the connection between the client and server is held open until one of the parties closes it. The difference between these two protocols is a bit like having a conversation over walkie-talkie (HTTP requests) vs talking on the telephone (WebSockets). With walkie-talkies, one person talks at a time, and thus the line is only ever open in one direction at a time. When talking over the phone, both parties can speak at anytime, and the connection remains open until someone hangs up.

All WebSocket connections start out as normal HTTP requests with a special header. This header informs the server, “Hey, FYI, I should be treated as a WebSocket connection; please keep the door open.” Its then up to the server to “upgrade” the connection to WebSockets, and from there, the client and server are free to send information back and forth at will.

The Challenge of WebSockets on Next.js

If you’re used to deploying your Next.js apps on serverless architecture, WebSockets don’t work out of the box. Serverless functions are built to be spun up and spun down as fast as possible and don’t accommodate long-running connections. It’s possible to use third-party services to add WebSocket support, but that isn’t your only option.

When deploying your app on Fly.io, your app runs as a traditional server, and thus WebSocket implementation is very straightforward; no third-party tools necessary. Additionally, Fly Machines are actually just fast-booting micro virtual machines that are managed by Firecracker (the same virtualization engine behind AWS Lambda). And unlike traditional servers that stay running, even when not in use, Fly Machines can be configured to automatically start and stop based on demand. Yay for only paying for what you use!

Building a Next.js App with WebSockets

We’re going to build a very simple chat application that uses WebSocket to allow multiple clients to send and receive messages in realtime. Since the purpose is just to illustrate how one could use WebSockets with Next.js, we’ll be making this dead simple: no authentication, no users, just an input where you can send a message for all clients to see.

Now, as we learned before, WebSockets need to be upgraded on the server to maintain the connection, and so we’ll be building a custom server for Next.js.

Let’s start out with a fresh Next.js install. We won’t be needing any styling for this mini-project, so skip Tailwind for now.

npx create-next-app@latest

Next, let’s install the dependencies we’ll need for our custom server:

npm i express ws

Creating the custom server

At the root of your application create a file called server.js with the following content:

 // server.js
const { parse } = require('url');
const express = require("express");
const next = require('next');
const WebSocket = require('ws');
const { WebSocketServer } = require('ws');
const app = express();
const server = app.listen(3000);
const wss = new WebSocketServer({ noServer: true });
const nextApp = next({ dev: process.env.NODE_ENV !== "production" });
const clients = new Set();
nextApp.prepare().then(() => {
 app.use((req, res, next) => {
 nextApp.getRequestHandler()(req, res, parse(req.url, true));
 });
 wss.on('connection', (ws) => {
 clients.add(ws);
 console.log('New client connected');
 ws.on('message', (message, isBinary) => {
 console.log(`Message received: ${message}`);
 clients.forEach(client => {
 if (client.readyState === WebSocket.OPEN && (message.toString() !== `{"event":"ping"}`)) {
 client.send(message, { binary: isBinary });
 }
 });
 });
 ws.on('close', () => {
 clients.delete(ws);
 console.log('Client disconnected');
 });
 });
 server.on("upgrade", (req, socket, head) => {
 const { pathname } = parse(req.url || "/", true);
 // Make sure we all for hot module reloading
 if (pathname === "/_next/webpack-hmr") {
 nextApp.getUpgradeHandler()(req, socket, head);
 }
 // Set the path we want to upgrade to WebSockets
 if (pathname === "/api/ws") {
 wss.handleUpgrade(req, socket, head, (ws) => {
 wss.emit('connection', ws, req);
 });
 }
 });
})

 

Let’s take a look at this section here, as this is what you’d want to change to tweak the app behavior when a new message arrives via a WebSocket channel:

 ws.on('message', (message, isBinary) => {
 console.log(`Received message: ${message}`);
 clients.forEach(client => {
 if (client.readyState === WebSocket.OPEN && (message.toString() !== `{"event":"ping"}`)) {
 client.send(message, { binary: isBinary });
 }
 });
});

 

We’re building a realtime chat app, so the only thing we need our WebSocket server to do is send the message received back to each client, and that’s what we’re doing above.

Another significant section of our custom server is this:

 if (pathname === "/api/ws") {
 wss.handleUpgrade(req, socket, head, (ws) => {
 wss.emit('connection', ws, req);
 });
}

 

This is the path we will use in our client code to initiate a WebSocket connection. It doesn’t matter what this route is, as we won’t actually be creating a file-based route in Next.js like you normally would. In fact, this is all the code we need to make this route usable.

Finally, in order to use our custom server, we’ll need to update our start command from next start (or next dev) to something else:

 ...
 "scripts": {
 ...
 "dev": "node server.js",
 "start": "node server.js"
 ...
 },
...

 

What about TypeScript? It’s more common to see custom servers written without TypeScript (using CommonJS), since otherwise you’d need to transpile the code first, or use something like ts-node. If you’re using a runtime that supports TypeScript out of the box, such as Deno or Bun, this is less of a concern.

Adding the client-side code

Now that we have our Next.js app running on a custom server that handles WebSocket requests, let’s finally build our chat app!

Replace the homepage of your app with the following code (it doesn’t matter if you’re using the Pages or the App router). I’ll be using the App router.

 // app/page.tsx
// "use client" only necessary for App Router
"use client"
import { useState, useEffect } from 'react';
let webSocket: WebSocket;
if (typeof window !== "undefined") {
 const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
 webSocket = new WebSocket(`${protocol}//${window.location.host}/api/ws`);
 setInterval(() => {
 if (webSocket.readyState !== webSocket.OPEN) {
 webSocket = new WebSocket(`${protocol}//${window.location.host}/api/ws`);
 return;
 }
 webSocket.send(`{"event":"ping"}`);
 }, 29000);
}
const Index = () => {
 const [messages, setMessages] = useState<string[]>([]);
 const [newMessage, setNewMessage] = useState('');
 useEffect(() => {
 webSocket.onmessage = (event) => {
 if (event.data === "connection established") return;
 setMessages((prevMessages) => [...prevMessages, event.data]);
 };
 }, []);
 const sendMessage = () => {
 webSocket.send(newMessage);
 setNewMessage('');
 };
 return (
 <div>
 <h1>Real-Time Chat</h1>
 <div>
 {messages.map((message, index) => (
 <div key={index}>{message}</div>
 ))}
 </div>
 <input
 type="text"
 className="border border-gray-400 rounded p-2"
 value={newMessage}
 onChange={(e) => setNewMessage(e.target.value)}
 placeholder="Type your message..."
 />
 <button onClick={sendMessage}>Send</button>
 </div>
 );
};
export default Index;

 

Let’s try running this code! Start your development server and then open http://localhost:3000 in two tabs. You should see the following:

If you type a message and click “Send”, you should not only see your message inserted above, but it should be visible in both tabs. This is because each tab creates its own WebSocket connection and our server is configured to send back the messages to all clients.

And there you have it! An extremely paired down chat application. Who needs Slack?

Deploying our chat app to Fly.io

As mentioned before, using WebSockets on Fly.io doesn’t require any special work, so let’s deploy our new chat app!

We can do this with one command, which will also generate a Dockerfile for us as well as a fly.toml:

fly launch --name <your-app-name>

And that’s it! If you run fly open you should see your live application at https://<your-app-name>.fly.dev

Conclusion

The documentation for using WebSockets on Next.js is a bit lacking, but that doesn’t mean it’s hard to implement. After this article, you now have a primer to help build more elaborate realtime Next.js services on Fly.io.

Build a file sharing service without making your brain hurt

2024年05月23日T00:00:00+00:00

We’re Fly.io. We make hard things easy, including deploying your apps around the world, close to your users. This post is about scaling a file sharing app using Fly.io and Tigris.

I’m a pretty online person, and I have friends all around the world. We tend to do things like share mod files and video replays pretty frequently, and this creates issues when the >5 GB file someone just uploaded in Poland needs to be downloaded in Canada.

Most if not all messaging services will have this problem, uploads go either to a local storage backend to the uploader, which makes reads slow anywhere else, or they go to the big bucket in Virginia and everything is slow for everyone.

This sort of thing is annoying enough that I’ve wanted a better solution for a while: a simple file sharing service that is fast for everyone, no matter who’s sending what to who.

I’ve tried to solve this problem before. I’ve looked at using off-the-shelf solutions, but I’ve found them either too complex or too simple, and so I had the itch to DIY it so I can control the implementation.

The must-have list for the new service:

Uploads and downloads to be fast regardless of who is sharing to who, this means handling files moving across oceans easily.
Some control over access, and the ability to add features easily.
Reasonable fault tolerance, we don’t need enterprise HA but not someone’s home server either

To achieve those goals, I’ve resurrected this idea with the ensemble cast of Tigris, Fly.io and SvelteKit, which are some of my favourite tools that help me make complex stuff without turning my brain into goo.

SvelteKit makes the frontend a breeze with easy HTML form handling and SSR out of the box, and Fly.io and Tigris give me global object storage on demand and compute to match.

So, how can Fly.io, Tigris and SvelteKit make this hard thing easy?

Building Soar

I’ve dubbed the file sharing service “Soar”, just to give it a bit of personality.

Soar is a pretty tiny full-stack SvelteKit app, only about 100 lines of important code. It takes user uploads via a normal HTML form, processes them in a SvelteKit form action, and returns info about the uploaded file to the user.

Step 0: Setting up a SvelteKit project

I’m using Bun for this project’s package manager, but you could swap in npm, pnpm, yarn, or whatever instead.

 # Create the project
$ bun create svelte@latest my-app
# Install dependencies
$ cd my-app
$ bun install
# Run the dev server
$ bun --bun run dev

 

Step 1: Uploading files to Tigris

The first half of a file sharing service is getting stuff from users’ computers into the storage backend.

There’s a few approaches we could take here, but we’re going to go with running the file uploads through the SvelteKit server, which keeps the client lean and means it works pre-hydration (it uses normal browser forms).

We can start by adding storage to our app, which we can do right from the flyctl CLI.

fly storage create

Name this something like “soar-dev” since we’re going to use a different bucket for our deployment later.

And we put our credentials into a file called .env.development in our project root.

 AWS_REGION="auto"
AWS_ENDPOINT_URL_S3="https://fly.storage.tigris.dev" # or a local S3 server
AWS_ACCESS_KEY_ID="..."
AWS_SECRET_ACCESS_KEY="..."
BUCKET_NAME="soar" # This is the name of our Tigris storage bucket

 

Now, let’s get to building.

S3 Client

We need to pull in the AWS S3 SDK to use the S3 API from our code:

# Install the aws-sdk packages we're going to use
$ bun add --dev @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner nanoid

Then we can use our credentials to create an S3 client for our server code to use later:

/src/lib/storage.ts

 import { env } from "$env/dynamic/private";
import { S3Client } from "@aws-sdk/client-s3";
export const S3 = new S3Client({
 region: env.AWS_REGION,
 endpoint: env.AWS_ENDPOINT_URL_S3,
 credentials: {
 accessKeyId: env.AWS_ACCESS_KEY_ID,
 secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
 },
 forcePathStyle: true,
});

 

Upload UI

This is made easy by Svelte’s similarity to HTML, we just plop down an HTML form with some props set to make it all work once we go to the server side.

action="?/upload" is a bit of SvelteKit magic that routes our form submit to a particular handler.
enctype="multipart/form-data" is HTML spec magic speak for “upload the whole file instead of just the name”
use:enhance is a Svelte action that makes the form submit smoother (no page reload) when JS is available.

/src/routes/+page.svelte

 <script lang="ts">
 const { form } = $props();
 import { enhance } from "$app/forms";
 let loading = $state(false);
 function submit() {
 loading = true;
 return async ({ update }) => {
 await update();
 loading = false;
 };
 }
</script>
<h1>Welcome to Soar</h1>
<form
 action="?/upload"
 method="post"
 enctype="multipart/form-data"
 use:enhance={submit}
>
 <input type="file" name="file" />
 <div>
 {#if loading} uploading... {:else if form?.error}
 <span>An error occured: {form.message}</span>
 {/if}
 </div>
 <button disabled="{loading}" type="submit">submit</button>
</form>

 

And on the server…

This is a little more complex, but all we’re doing here is using the special SvelteKit export actions to handle the aforementioned ?/upload action.

 export const actions: Actions = {
 async upload(e) {
 ...
 }
};

 

We pull the file out of the form data:

 const data = await e.request.formData();
const file = data.get("file") as File;

Do a little check that it’s actually there:

 if (!file.name || file.name == "undefined") {
 return fail(500, { error: true, message: "You must provide a file" });
}

 

Then upload it to S3 using the client we created earlier.

 const key = nanoid() + "_" + file.name;
const upload = new Upload({
 params: {
 Bucket: env.BUCKET_NAME,
 Key: key,
 Body: file,
 ContentType: file.type,
 },
 client: S3, // Imported from $lib/server/storage
});
await upload.done();

 

And finally, redirect the user to the uploaded file.

 redirect(303, `/${key}`);

 

And, uploading works!

The magic Tigris provides us here is when we scale our SvelteKit app to new regions, Tigris is already there, ready to go. We don’t have to pay more or do anything at all. We automatically get our uploads going from user -> our app -> Tigris in the nearest region. This lowers latency, improves bandwidth and reliability by eliminating possible bottlenecks.

We could make the uploads even more direct by using presigned URLs but it complicates the code by requiring a two-step upload process.

Step 2: Retrieving files from Tigris and displaying them to the user

Now that we’ve uploaded a bunch of cat photos, mod files and database credentials to our service, we need a way to retrieve uploaded objects.

This is similarly easy, and we can do most of the work server-side with a load function inside +page.server.ts:

 export async function load(e) {
 const metadata = await S3.send(
 new HeadObjectCommand({ Bucket: env.BUCKET_NAME, Key: e.params.file })
 );
 const url = await getSignedUrl(
 S3,
 new GetObjectCommand({ Bucket: env.BUCKET_NAME, Key: e.params.file }),
 {
 expiresIn: 3600,
 }
 );
 return { url, metadata };
}

 

We grab the metadata of the object, create a pre-signed URL for accessing the file contents, and send it off to our future selves in frontend-land.

This all runs on the server, which means we can implement authorization checks or rate limits or whatever else here. Unlike uploads, we use pre-signed URLs here so users are always pulling the file from the closest Tigris region.

Alternatively, we could proxy the body of the object through our app. This would offer stronger authorization guarantees, but would mean users would retrieve the potentially large file through the closest instance of our app, not necessarily the closest Tigris region.

A little sprinkle of frontend, and we have working file retrieval!

 <script lang="ts">
 const { data } = $props();
 const embedType = data.metadata.ContentType?.split('/')[0];
</script>
{#if embedType == 'image'}
 <img class="block" src={data.url}" />
{:else if embedType == 'video'}
 <video class="block" src={data.url}></video>
{/if}
<a href={data.url}>raw</a>

 

This is a happy middle ground between making the bucket public and proxying uploads through the SvelteKit app. It gives us the benefits of serving the files directly from Tigris, while retaining most of the control over who can access what.

When users request a file, Tigris will do the right thing automatically. If an object is requested in a different region than the one it was uploaded to, the file will transparently be copied to that region when it is requested, making subsequent access as fast as the region where it was initially uploaded.

This is sometimes referred to as "Pull-through" caching. Tigris actually supports caching on put and caching on list as well.

Step 3: Where’s the rest of the code?

When I got to this point, I was left with a bit of wonder at how quickly everything comes together with today’s “magic” tooling. SvelteKit handles the frontend, data loading, uploading and storing with no fuss, Tigris just does the right thing without us telling it to, and getting it ready to deploy on Fly.io happens pretty much automatically.

Ship it!

Currently, you have to swap out adapter-auto for adapter-node in svelte.config.js manually before you can deploy to Fly.io. We’re working on making this easier in the future.

 $ fly launch --no-deploy
$ fly storage create # Production bucket
$ fly deploy

 

Scale it…

$ fly scale count 3 --region ewr,waw,lhr

What comes next

For me, not much. This project exists only as a KISS file uploader for me and a few of my friends. For you, there’s a few directions we could take this:

Add an accounts system to namespace and track previous uploads
We could add this functionality if you wanted to offer a sort of “index” for a given uploader, maybe with public / private files.
Build an API for uploading objects
We could use this to integrate with image/file sharing applications like ShareX, or build a CLI uploader.

For more interesting things to do with Tigris and Fly, check out these articles:

Multi-tenant apps with single-tenant SQLite databases in global Tigris buckets

2024年04月17日T00:00:00+00:00

We’re Fly.io, where apps run on Fly Machines—fast-starting VMs with a simple API—in 30+ regions around the world. This article is about Fly Machines storing their SQLite databases in a globally distributed Tigris bucket. If you haven’t tried Machines, take them for a spin! It’s fast to get started.

I got nerd-sniped by one of the ideas Jason brainstormed in his Phoenix Files article about Tigris, an S3-compatible globally synced object store. Tigris is, not coincidentally, built on Fly.io. (If you haven’t read Jason’s article, go read it! You’ll be fine! There’s hardly any Elixir in it.)

Here’s the idea I’m here to explore: multi-tenant applications with single-tenant SQLite databases stored in Tigris and run on single-tenant Fly Machines:


The multi-tenant architecture with single-tenant SQLite databases.

If we’re to handle a tenant request within this architecture, we’d route the request to its Machine, ensure its database is there, serve the request, update database file in the bucket… and potentially auto-stop the Machine if that was just a one-off request! (And yes, we can also wake it up if another request comes in.)


The sequence diagram

To learn more about Tigris, go here. To learn about Fly Machines, go here.

However, there’s a caveat to this approach: if we allow more than one Machine concurrently access the tenants’ SQLite database, the Machine updating the database file in the bucket last would overwrite changes done by the other ones. Also, these Machines would work on snapshots of the data without knowledge of the changes applied in parallel.

That’s enough rambling about theory! Let’s bring this idea to life. In this post, we’ll build a Vanilla JavaScript app that keeps a counter in a SQLite database and increments it every time a user visits a web page. It’ll fetch the database file from Tigris on the app start-up and send it back on shutdown. At the end, we’ll make the app customizable so that an instance can be run per tenant and deploy a multi-tenant setup at Fly.io.

Actually, I’ve already build the app at: https://github.com/fly-apps/js-sqlite-in-tigris… let’s go through it step by step together!

If you want to run the examples, make sure you’ve got a Fly.io account.

Tigris setup

Issue fly storage create to create a Tigris project. This will output a bunch of environment variables that have to be available in the shell to run the following examples. The environment variables are important. If they’re not set, the following examples won’t work.

The simplest way to set them up is to issue a set of export statements in your shell:

 export AWS_ACCESS_KEY_ID=<you-access-key-id>
export AWS_ENDPOINT_URL_S3=https://fly.storage.tigris.dev
export AWS_REGION=auto
export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
export BUCKET_NAME=<your-bucket-name>

 

To keep the variables handy, install a tool like dotenv and put the exports into a .envrc file. dotenv will make them available for the shell commands run inside the current directory.

Get the feel of Tigris with the AWS CLI:

 aws s3api list-buckets # you should see the bucket you've created on setup 
aws s3api put-object --bucket $BUCKET_NAME --key mykey --body sampe-file # put a file into a bucket
aws s3api list-objects-v2 --bucket $BUCKET_NAME # list objects in the bucket
aws s3api get-object --bucket $BUCKET_NAME --key mykey sample-file # download the file
fly storage dashboard $BUCKET_NAME # see the bucket in the Tigris console

 

Now, let’s switch gears and focus on the JS app and SQLite for a bit.

Node.js app with SQLite

The code corresponding with this step is available at 7303da9.

It’s pretty easy to start building with our Node generator. You can install it with npx --yes @flydotio/node-demo@latest (more on it here).

With that installed, if you run npx node-demo --esm --ejs --express --sqlite3 and make a few tweaks for our use case, you’ll get an example Vanilla JavaScript app running Express server with SQLite. To test it locally, start the server: npm install & npm run start

If you visit http://localhost:3000/ and start refreshing the page, you’ll see a counter incrementing. If you restart the app, the counter should pick up where it left off - we do persist our state to the database, great!

Nothing fancy here code-wise:

we create and set up an SQLite database:

 // server.js
process.env.DATABASE_PATH ||= './db.sqlite3'
const db = new sqlite3.Database(process.env.DATABASE_PATH)
...
db.run('CREATE TABLE IF NOT EXISTS "welcome" ( "count" INTEGER )')

 

configure the Express server to listen at port 3000:

 // server.js
const app = express()
...
// set up static content and ejs views
app.use(express.static('public'))
app.set('view engine', 'ejs')
...
app.listen(3000, () => {
 ...
})

 

and expose a page to increment the counter in the database:

 // server.js
app.get('/', async(_request, response) => {
 // increment count, creating table row if necessary
 await new Promise((resolve, reject) => {
 db.get('SELECT "count" from "welcome"', (err, row) => {
 let query = 'UPDATE "welcome" SET "count" = ?'
 if (err) {
 reject(err)
 return
 } else if (row) {
 count = row.count + 1
 } else {
 count = 1
 query = 'INSERT INTO "welcome" VALUES(?)'
 }
 db.run(query, [count], err => {
 err ? reject(err) : resolve()
 })
 })
 })
 // render HTML response
 response.render('index', { count });
})

 

And that’s the essence of the functionality our app will be providing to our users. Let’s see how we can store the database file in Tigris.

Store the tenant database file in Tigris!

The code corresponding with this step is available at d8496f6.

If you played with Tigris in one of the previous sections, you probably know what we’re going to do now: just grab the db.sqlite3 file and store it in our bucket! Not only that, but we’ll also parametrize the app so that it knows what tenant it is supposed to serve.

To make the latter work, we make the app read the CUSTOMER_ID environment variable and parametrize the route path with it:

 // server.js
const customerId = process.env.CUSTOMER_ID || 0
...
app.get(`/customers/${customerId}`, async (request, response) => {
 // the counter logic
})
app.get(`/customers/:customerId`, async (request, response) => {
 response.status(403).send();
})

 

If we get a request to a CUSTOMER_ID that we’re not serving, 403 will be returned.

To talk to Tigris, we’ll use the @aws-sdk/client-s3 library - as with any other S3-compatible service. For this to work, we need to set up our S3 client to point at the Tigris endpoint:

 // server.js
const S3 = new S3Client({
 region: "auto",
 endpoint: `https://fly.storage.tigris.dev`,
});

 

We also need to read our bucket name and construct the object key under which we’ll store a customer’s database file:

 // server.js
const bucketName = process.env.BUCKET_NAME
const databaseKey = `/customer/${customerId}/db.sqlite3`;

 

On the server startup, we retrieve the database file from the bucket, or we’ll use the pre-created one:

 // server.js
const db = new sqlite3.Database(databasePath) // that file gets overwritten
...
const checkDbInS3 = async () => {
 try {
 const { Body } = await S3.send(new GetObjectCommand({
 Bucket: bucketName,
 Key: databaseKey
 }));
 fs.writeFileSync(databasePath, await Body.transformToByteArray());
 } catch (error) {
 // error handling
 }
};
...
checkDbInS3();

 

On the server shutdown, we’ll be uploading the database file to the bucket:

 const sendDbToS3 = async () => {
 try {
 const fileContent = fs.readFileSync(databasePath);
 await S3.send(new PutObjectCommand({
 Bucket: bucketName,
 Key: databaseKey,
 Body: fileContent
 }));
 process.exit(0);
 } catch (error) {
 process.exit(1);
 }
};
...
process.on("SIGINT", sendDbToS3);
process.on("SIGTERM", sendDbToS3);

 

And that’s it for storing our tenant’s database file in Tigris!

Little reminder: to be able to run the examples in this post, the environment variables mentioned in the Tigris setup section must be exported in the shell you run the examples in.

If you want to make your hands dirty, give it a try: npm install && CUSTOMER_ID=10 npm start run

Jump to http://localhost:3000/customers/10 to see it in action. The server logs should be telling us we fetch/store data from/in Tigris:

 > start
> node server.js run
Server is listening on port 3000, serving customer_id: 10
Successfully downloaded the db file from S3.
[customer_id=0] Received request for customer: 10
[customer_id=0] Received request for customer: 10
[customer_id=0] Received request for customer: 10
^CSuccessfully sent the db file to S3. # NOTE that I'm sending Ctrl+C here

 

You can always fly storage dashboard $BUCKET_NAME to see the bucket on the Tigris console.

That’s great! Try to run the app as a different customer, that should start counting from the beginning; remember to remove the db.sqlite3 file: rm db.sqlite3 && CUSTOMER_ID=300 npm start run.

OK, you’ve got pretty far already... ready for a big thing?

The big thing #1: deploy to Fly.io

Actually…I should have said #2 since the #1 big thing was to set up Tigris and use it! But I guess it was easy enough not to notice! But let’s reflect on it: your SQLite database can now be served from servers close to your users since it will be automatically cached in the regions it will be accessed from.

Anyhow, let’s jump straight to the deployment part. If you want to follow the easy path, check out commit 87ab970 and:

Supply the app name in the fly.toml: app = '<app-name>'
Create the app at Fly.io: fly apps create <app-name> (an app is just a bag of resources on our platform)
Make the secrets available in the app’s Machines (this assumes you have the $AWS_* variables exported as described in the Tigris setup section):
```
fly secrets set AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID
fly secrets set AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY
```
Allocate an IP address for the app: fly ips allocate-v4 --shared

Run a machine for a customer (single tenant):

 fly machine run . --name customer10 --port 443:3000/tcp:http:tls \
--env CUSTOMER_ID=10 \
--env AWS_REGION=$AWS_REGION \
--env AWS_ENDPOINT_URL_S3=$AWS_ENDPOINT_URL_S3 \
--env BUCKET_NAME=$BUCKET_NAME

 

Fire up logs to see as things are happening: fly logs
Visit the https://<app-name>.fly.dev/customers/10 and celebrate 🎉
Kill the Machine with fly machine destroy --force

The slightly harder path involves generating the Dockerfile and fly.toml on your own. We’ll use fly launch for that and customize them a little. To the point:

Check out the repo at commit d8496f6
Issue fly launch --build-only --no-deploy --name <app-name> and decline tweaking the settings
Clean up the generated files so that they reflect what’s in the repo at this commit

Then follow the easy path 3-7 steps and… Wow! We’re live now.


Refreshing the `https://<app-name>.fly.dev/customers/10`

Couldn’t we just go multi-tenant by spinning up multiple machines for our customers and call it a day? If you give it a try you’ll quickly bump into a routing/port assigning mess - and this is the big thing #2 we’ll tackle!

The big thing #2: multi-tenancy with `fly-replay`

For this to work, we’ll need:

Dynamic Request Routing - to route requests to the tenants’ machines,
Fly.io internal addressing - to lookup a Machine ID we want to route a request to,
Machine’s metadata - to mark a machine with its CUSTOMER_ID so we can easily discover them using our tenants’ IDs.

Wow, that was probably the most buzzword-intensive statement in this post, but bear with me - it will work, it will make sense, and life will be beautiful again ❤️. Anyhow, if you are curious, see our Globally Distributed Postgres post to see how powerful are the features we’re dealing with here.

If there’s more than one Machine exposing the same service, the Fly Proxy will load balance requests to our app across all of them (this is how our proxy works by default). This is not what we want since a request for a given customer must reach its machine.

The way to achieve this is to make each machine execute business logic and act as a router for our app and replay requests that are not destined for it. For example, if a machine for customer 100 gets a request for customer 200, it will route the request to the customer’s 200 machine. If there’s no machine for a given customer, 404 will be returned. The following diagram depicts a request flow in which a Machine acts as a router:


Tenant-1 user gets load-balanced to a Tenant-2 Machine (2), which replays the request to Tenant-1 (3-4) machine, where it gets served.

At the high level, we’ll have 2 Express routes: one for the CUSTOMER_ID the Machine is running for and the other one for the routing:

 // server.js
const customerId = process.env.CUSTOMER_ID || 0
...
app.get(`/customers/${customerId}`, async (request, response) => {
 // business logic (the counter) for the CUSTOMER_ID this machine IS serving
});
app.get(`/customers/:customerId`, async (request, response) => {
 // routing logic for CUSTOMER_IDs this machine IS NOT serving
 let machineId = await get_machine_id(request.params.customerId);
 if (machineId) {
 response.set('fly-replay', `instance=${machineId}`).send();
 } else {
 response.status(404).send("Not found");
 }
})

 

If the get_machine_id(request.params.customerId) returns a valid machineId, we set the fly-replay HTTP header with that customer’s machineId and send a response back. Because of the header, the proxy won’t return the response to the caller but will replay the request to the given machine. That way, each tenant hits its instance.

Now, how does the get_machine_id(request.params.customerId) work? It relies on each machine having a CUSTOMER_ID metadata key being set. That allows us to make a DNS lookup to fetch a customer’s machine IPv6 via a special address: dig aaaa +short <CUSTOMER_ID>.customer_id.kv._metadata.<app-name>.internal. Having the IP address, we can do one more lookup (a reverse one) to fetch the machine ID that we need for the fly-replay header: dig +short -x fdaa:6:32a:a7b:23c8:3d9b:fe49:2 (the last argument is an example IPv6 address of a Machine).

The get_machine_id(customerId) function uses the node-dig-dns package to implement these queries in JS:

 // server.js
const appName = process.env.FLY_APP_NAME;
const get_machine_id = async (customerId) => {
 // return a sample ID the app is not deployed on Fly.io
 if (!appName) { return "abcd1234" };
 try {
 const ip = await dig([`${customerId}.customer_id.kv._metadata.${appName}.internal`, 'aaaa', '+short'])
 const addr = await dig(['+short', '-x', ip]);
 return addr.split('.')[0];
 } catch (error) {
 // error handling
 }
};

 

node-dig-dns requires the dnsutils OS package, thus we install it in the Dockerfile.

You may have spotted the addr.split('.')[0]. This is to extract only the 1st segment of the returned string since the reverse lookup (the one with -x) returns an FQDN address, e.g.: 3d8dd15c1ed778.vm.jts.internal..

Finally, how do we set that metadata? There are a few ways to do that, like with an API, but we will do that at the machine startup as fly machine run ... --metadata customer_id=100.

Lastly, let’s put the cherry on the cake and deploy the whole thing for 3 customers. Take it easy, check out the main branch, and providing you’ve set up the <app-name>, secrets, and the IPv4 address as described in The big thing #1, then just execute the following:

 for i in `seq 1 3`; do
 fly machine run . --name customer${i}00 --port 443:3000/tcp:http:tls \
 --env CUSTOMER_ID=${i}00 \
 --env AWS_REGION=$AWS_REGION \
 --env AWS_ENDPOINT_URL_S3=$AWS_ENDPOINT_URL_S3 \
 --env BUCKET_NAME=$BUCKET_NAME \
 --metadata customer_id=${i}00
done

 

That will spin up Machines for customers with IDs 100, 200 and 300 and make your app available at https://<app-name>.fly.io/customer/<CUSTOMER_ID>.

That’s is it! We’ve made it - we have a demo multi-tenant application with exclusive computing with Machines and data storage with SQLite database hosted at Tigris.

Conclusion

There are a number of things that we could elaborate on here, but let me focus on just two things: automating tenant provisioning and scalability aspects of the app we’ve built.

I will start with the former because it’s simpler: we have all the tooling to automate tenant provisioning and its lifecycle management. The Machines API makes it possible to programmatically create and manage the lifecycle of the machines. Also, by tweaking the machines config appropriately, we can instruct the proxy on things like automatic shutdown or wake-up. That’s probably a big topic for another post, so I will just stop here.

When it comes to scalability, our approach is far from perfect since if we had more than one customer Machine (i.e., if we attempted to scale horizontally), we’d end up mutating the SQLite database in parallel, which would result in overwrites. One possible solution to this problem would be to transactionally create a machine.lock file in a customer bucket containing the Machine’s ID that performs the DB mutations at the current moment. That would possibly allow a Machine failing to acquire the lock to fly-replay the request to the one holding it. Once the “mutator” is done, the lock will be released by removing the file.

Tigris allows for Conditional Operations, which would help ensure that only one request creates the lock file and all the other concurrent ones would fail.

Happy multi-tenanting!

Building a Remix app locally with Docker

2024年04月15日T00:00:00+00:00

Fly.io makes it easy to deploy containerized apps in seconds. The more comfortable you are with Docker, the smoother and more reliable your deployments can be. Let’s learn how to leverage Docker when developing your app locally!

Docker can give developers a high degree of confidence that their applications will run exactly as expected in production. However, many people still run into failed deployments or unanticipated problems because when developing locally, the aren’t using Docker. In this article, we’re going to explore how to setup your Remix local environment to use Docker in development.

In the end, we’re going to be able to run our application locally as a Docker image that will live reload as we make changes.

Create a new Remix app

Let’s start by instantiating a new Remix app with the default template:

npx create-remix@latest

As of right now, the default template for Remix uses Vite. In order the allow the Vite server to be exposed to Docker later on, we need to make a change to our dev script in our package.json by adding --host :

 "scripts": {
 ...
 "dev": "remix vite:dev --host",
 ...
}

 

If you happen to be using a version of Remix that does not use Vite, this step isn’t necessary. With our Remix app initiated, let’s try running it locally:

npm run dev

With this running, we can visit localhost:5173 in our browser (or port 3000 if not using Vite) and see our sample app up and running:

Hooray!

Before we set up our local environment to use Docker, let’s deploy our app as-is to Fly.io. This will set us up with the foundational Dockerfile that we’ll rely on in configuring Docker Compose for local development.

Deploy to Fly.io

If this is your first time deploying to Fly.io, you’ll want to start by downloading the CLI flyctl, as this is the primary method you’ll use to interact with the platform.

Once installed, all you need to do is run two commands:

fly launch

This auto-generates a fly.toml (required config for Fly Apps) and a Dockerfile. The generated Dockerfile is specific to Remix, so no need to change a thing. 😃

Next, deploy you application to Fly.io:

fly deploy

Once completed, your app should be available at https://<YOUR-APP-NAME>.fly.dev

Now that we have our app running on Fly.io we can get to work setting up our local environment. To do so, we’ll be relying on Docker Compose.

What is Docker Compose and why do I need it?

Working with Docker involves two steps:

Building the Docker image
Running the Docker image in a container

These both require separate commands, often with a slew of extra parameters to set things like exposed ports, volumes, bind mounts, environment variables, and more. These commands can get quite long and tedious to remember.

Docker Compose is a way of defining params you’d normally pass to your build and run commands into a single docker-compose.yml file. This way, all you need to do to get your app running in a Docker container is:

docker-compose up -d --build

Docker Compose is an invaluable tool for local development, as you’ll soon see. Let’s try using it with our Remix app.

Docker Compose for local development

First, we need to make a small change to our Dockerfile so our app runs as expected in development mode. Search for this line, which removes all devDependencies:

 RUN npm prune --omit=dev

 

Replace this with the following, so the command only runs when our app is in production:

 RUN if [ "$NODE_ENV" = "production" ]; then \
 npm prune --omit-dev; \
 fi

 

Next, create a file called docker-compose.yml at the root of your project:

 version: "3.8" # this the version of Docker Compose
services:
 app:
 build:
 context: ./ 
 command: npm run dev
 environment:
 - NODE_ENV=development
 ports:
 - '5173:5173'

 

A number of these settings allow us to override things defined in our Dockerfile, things like environment variables and the command to start our application. In this case, we’re overriding the NODE_ENV variable to development, as well as the start script to npm run dev . We can now run our app in a container with the command:

docker-compose up -d --build

Once completed, you’ll be able to access your app at localhost:5173. However, any changes that you make to your code won’t be reflected unless you were to rebuild the image! That’s no good for local development, so let’s fix that.

Making local changes available

We’ll be using a feature of Docker called bind mounts to allow our code changes to pass through to the container. To do this, we’ll be setting the top-level volumes key in our Docker Compose settings like so:

 version: "3.8" # this the version of Docker Compose
services:
 app:
 build:
 context: ./ 
 command: npm run dev
 environment:
 - NODE_ENV=development
 ports:
 - '5173:5173'
 volumes:
 - ${APP_DIR}:/app
 - /app/node_modules

 

This volumes key in Docker Compose configures both bind mounts and volumes.

Bind mounts follow the pattern </local/path>:</path/in/docker/image>, which tells Docker to use the files from the underlying filesystem instead of what’s bundled in the image.

You can think of bind mounts as a way to “cut a hole” in the Docker image to allow the underlying files on your computer to pass through.

In our case, ${APP_DIR}:/app allows us to make changes to our app code that will be reflected in our running container. You can set APP_DIR in a .env file, and it should be the absolute path to your application directory.

Using an anonymous volume for `node_modules`

By using a bind mount, we’re now letting our whole application codebase pass through to the container, and this includes node_modules , and that’s a problem, but it might not be obvious.

Some npm packages have platform-specific versions. For example, on macOS, esbuild will install the package @esbuild/darwin-arm64, but on Linux systems, @esbuild/linux-arm64 will be required. For this reason, we should not rely on the underlying filesystem for node_modules.

So, how do we tell Docker to exclude only this folder from our bind mount? Enter anonymous volumes.

Let’s look again at this section of our docker-compose.yml:

  volumes:
 # bind mount 👇
 - ${APP_DIR}:/app
 # anonymous volume 👇
 - /app/node_modules

 

While bind mounts are controlled by the host machine, volumes are controlled by Docker. In both cases, a parallel folder exists in the host filesystem, but in the case of volumes, instead of the host dictating what goes in it, Docker controls what goes in.

If we look in our Dockerfile, we’ll see that it runs npm ci --include-dev (basically npm install), and those dependencies get placed inside the directory /app/node_modules in our image . By adding - /app/node_modules as a volume, we’re letting Docker override the contents of our local node_modules folder in the image, thus avoiding the problem. In other words, we’re saying “Use the underlying host files for everything except node_modules.”

With our bind mount and volume set up, we can now run docker-compose up -d --build, and any changes to our code will be reflected in our container.

Live reload changes on non-Vite Remix apps

As stated earlier, the default templates for Remix now use Vite, which don’t require any extra setup for live reloading to kick in. However, if not using Vite, and your application normally runs on port 3000, you can add a second port entry to include 3001 like so:

  # ...
 ports:
 - '3000:3000'
 - '3001:3001'
 #...

 

For non-Vite Remix apps, live reloading operates through a web socket connection on port 3001. With this extra port exposed in our configuration, your changes will be available instantly in your container.

Conclusion

Leveraging Docker Compose for local development can give you the confidence that what you build locally will be reflected in production when you deploy your app. Docker gives you the most control over the environment in which your app runs, and Fly.io makes deploying containerized applications easy.

FLAME for JavaScript: Rethinking Serverless

2024年02月26日T00:00:00+00:00

We’re Fly.io. We run apps for our users on hardware we host around the world. This post is about fast launching a machine to run a JavaScript function as an alternative to a Lambda service. It’s easy to get started! with your JS app on Fly.io!

A couple of months ago, Chris McCord, the creator of the Phoenix framework, published an article about a new pattern called FLAME as an alternative to serverless computing. The original article focused on the implementation in Elixir, which has some unique clustering capabilities that make it exceptionally well-suited for the FLAME pattern, and this had some folks asking – what would FLAME look like in other languages?

Today we will explore some possible approaches to FLAME in JavaScript. These solutions are experimental and, as you’ll see, not without trade-offs, but let’s see how far we get!

What is FLAME?

As a quick recap, FLAME stands for Fleeting Lambda Application for Modular Execution. It auto-scales tasks simply by wrapping any existing code in a function and having that block of code run in a temporary copy of the app.

In JavaScript, it might look something like this:

 function doSomeWork(id) { ... }
// run `doSomeWork` on another machine
export default flame(doSomeWork, ...)

 

FLAME removes the FaaS labyrinth of complexity and is cloud-provider agnostic. While the Elixir library that Chris wrote is designed specifically for spinning up Machines on Fly.io, FLAME is a pattern that can be used on any cloud that provides an API for spinning up instances of your application.

For a more thorough rundown of FLAME, be sure to read Chris’s full article here: FLAME: Rethinking Serverless

What are Machines on Fly.io?

Fly Machines are the engine of the Fly.io platform: fast-launching VMs that can be started and stopped at subsecond speeds. Fly Machines themselves are not containers, but they do run your application code inside containers. You can read more about them here, but for this article, all you need to know is that Machines are just instances of your application code.

FLAME in vanilla, no-build JavaScript

As mentioned earlier, Elixir is uniquely suited to FLAME because of it’s clustering abilities. The main question for implementing this pattern in other languages is this: how do you run specific code blocks on an entirely different instance of your app?

In this post, we’re pulling back the curtain on the inner workings so you, as the developer, can feel more confident about using it in your app, but once you have a working FLAME library, you should just be able to drop it into your project and start making FLAME calls.

Overview

My teammate, Lubien, wrote a sample JavaScript app that implements FLAME a little differently than how it’s done in Elixir. You can find the complete files at https://github.com/fly-apps/fly-run-this-function-on-another-machine

So, how does it work?

Whenever we want to run a task on another Machine, we pass the code as a parameter to our FLAME function, which punts it off to be run on the other Machine, which we will call our runner Machine.

An important thing to understand is that this FLAME call is always executed twice, and it will return one of two functions:

The first time it’s run on our normal app instance and returns an anonymous function that...

First checks for existing runner Machines and spawns one if none are found. runner Machines are copies of our application code, but replace our starting process with a simple HTTP server.
Then, it makes a POST request to that runner Machine, with two parameters:
1. filepath – the absolute path to the file containing our FLAME-wrapped code
2. args – any arguments needed for the code inside your FLAME function

The second time it’s run will be on our runner Machine, and this time our original code block will be returned, to be executed with the args we passed in via our POST request.

With that overview out of the way, let’s dive into Lubien’s code.

The Files

In Lubien’s app, there are three files involved in pulling off our FLAME implementation:

index.mjs – This is where our application starts, and it calls the function containing our FLAME-wrapped code, runMath
runMath.mjs – This is where we import runMath from, and exports the returned value of our FLAME function. Unlike the Elixir implementation, all FLAME-wrapped tasks need to be exported as the default module in a given file.
flame.mjs – This is our FLAME library. This code is specific to spinning up Fly Machines, but again, this could just as easily be swapped for another cloud provider API.

Let’s open up each file and see how the magic works. ✨

index.mjs

Lubien’s FLAME app starts in ./index.mjs, which runs a single function, runMath:

 // index.mjs
import runMath from './runMath.mjs'
async function main() {
 const math = await runMath(100, 20)
 console.log(math)
}
main()

 

runMath.mjs

Inside of./runMath.mjs we find the following:

 // runMath.mjs
import flame from "./flame.mjs"
export default flame((a, b) => {
 return a + b
}, {
 path: import.meta.url,
 guest: {
 cpu_kind: "shared",
 cpus: 2,
 memory_mb: 1024
 }
})

 

This file doesn’t actually contain a function called runMath, but instead exports whatever flame returns. flame is roughly the equivalent of the Elixir FLAME.call method, and it returns a function.

flame accepts the following parameters:

originalFunc : The function you want to execute on another Machine; In this example, we’ve passed it as an anonymous function.
config:
- path: the path to the current file. This is what we’ll pass to our runner server as the filepath
- guest: the specs for the Machine you want to spin up

flame.mjs

Next, if we look inside ./flame.mjs we find a much longer file. As stated before, this is our FLAME library. This does a number of things, including code that...

Checks to see if there are any existing runner Machines
Spawns a new runner Machine if none are found
Boots up our simple HTTP server on our runner Machines
Schedules timeouts for our runner Machines to shut down
In a POST request, imports & runs our FLAME code block

Rather than step through every line in this file, we’re just going to focus on the flame function, but you can check out the commented documentation here: https://github.com/fly-apps/fly-run-this-function-on-another-machine/blob/main/flame.mjs

Let’s skip down to where flame is actually defined:

 // ./flame.mjs
...
export default function flame(originalFunc, config) {
 if (IS_RUNNER) {
 return originalFunc
 }
 const { 
 meta, 
 guest = {
 cpu_kind: "shared",
 cpus: 1,
 memory_mb: 256
 } 
 } = config
 const filename = url.fileURLToPath(config.path);
 return async function (...args) {
 if (!(await checkIfThereAreWorkers())) {
 await spawnAnotherMachine(guest)
 }
 return await execOnMachine(filepath, args)
 }
}
...

 

As mentioned before, our flame function is always called twice. Above we can see that it will either return our original function that we passed in, OR it will return an anonymous function that checks for runner Machines and sends a request to one.

Further up the file, we define how to handle POST requests on our runner Machine. This is where we import the module from the file that contains our FLAME call. This is the second time flame is called, and this time it returns our original function, which gets executed with the args passed to it.

 // ./flame.mjs
...
if (IS_RUNNER) {
 ...
 // get the request params `filepath` and `args`
 const { filename, args } = JSON.parse(body)
 // import the default module inside `filepath`
 // in this case, filepath = "./runMath.mjs"
 const mod = await import(filename)
 // run the default module (a function) and pass in `args`
 const result = await mod.default(...args)
 ...
}
...

 

And that’s it! FLAME implemented in vanilla JavaScript.

Understanding how this FLAME pattern works is very helpful, and once you have your FLAME library working for your preferred cloud provider (Fly.io or others), you can start abstracting any functions that you’d like to auto-scale with a FLAME wrapper, like so:

 export default flame(doSomeWork, ...)

 

Limitations of FLAME in JavaScript

The biggest limitation in the flow defined above comes down to the assumption that running our FLAME function is as simple as importing the file that contains it, and running the default module. This only works when you...

Have your FLAME-wrapped code block as the default export of a file
Are not mixing CommonJS and ES Module syntax
Are NOT using TypeScript 😢

It’s especially tricky with any transpiled code like TypeScript since it means you can’t simply import the file as is unless your HTTP server was using something like ts-node instead of node. For better performance, you could transpile all of your FLAME TypeScript code, but this would add extra files to your project that you may not want. If your application is using Bun or Deno, however, all these TypeScript problems are a non-issue, since those runtimes support it out of the box!

Using FLAME in a JavaScript framework

It’s entirely possible to drop the FLAME library into any JavaScript framework, such as Next.js, and have it work, provided that the above-mentioned prerequisites are satisfied. However, you’d have to ditch the TypeScript.

An alternative pattern could be running an exact copy of your web application, instead of using your app image and overriding the start command. In other words, instead of using a slimmed-down HTTP server on your runner Machines, you could stick with your standard npm run start (or whatever your start command is). This would likely require some extra configuration in your framework to handle the FLAME POST requests, however, so it’s not a perfect turn-key solution.

Cold starts & pooling

While Fly Machine cold starts are extremely fast, it still takes a few hundred milliseconds, so it’s still worth weighing the impact it has on performance. The code we’ve shown today will boot up a new runner Machine if none are found, which does incur cold start time. Luckily, it’s currently free (and soon, cheap) to have stopped Machines ready for near-instant start ups. For this reason, you may want to consider maintaining a pool of runner Machines that can quickly be started and stopped.

Autoscaling for request queuing

Now, even if we have a pool of runner Machines available at our beck and call, these could still become inundated with FLAME requests. A more production-ready implementation would need to have a way of scaling up runner Machines based on a given metric, such as response time.

Conclusion

Deploying on Fly.io makes this process even simpler by providing a convenient Machines API for scaling instances of your app. And while initial work of building a cloud-specific FLAME library requires a bit of work upfront, once done, you have an incredibly simple way of auto-scaling select tasks in your application.

Demystifying Docker for JavaScript

2023年12月12日T00:00:00+00:00

Dockerfiles for JavaScript applications can range quite a bit – from two lines to fifty. What gives? This complexity can drive some developers away from really understanding this powerful tool, so today, I’d like to demystify Docker by examining a sample Dockerfile for a JavaScript application. This should be a useful resource, regardless of what JS framework you work in.

While this article will not be a comprehensive education on the subject, by the end of this article, you’ll feel much more confident in your ability to write and modify any Dockerfile to suit the needs of your app.

A quick primer on Docker vocabulary

Some vocabulary:

Image: This contains your application code and everything needed to run it. For the most part, Docker images (or, more specifically, Open Container Initiative (OCI) images) are just a stack of filesystem layers. You can build a new image using docker build or with other tools like Podman. To learn more, check out the section on OCI Images in our blog post Docker without Docker.
Container: This is what actually runs your image and makes your app go zoom. You can run an existing Docker image using docker run. Setting up your container is typically where you would define things like environment variables, which ports to expose, which protocols to allow, etc.
Instructions: These are the bits in ALLCAPS at the start of each line, followed by any number of parameters. You might hear people call them commands or statements, but they are officially called instructions.
Layers: Almost every instruction line in a Dockerfile gets turned into a layer. These layers are the tarballs that make up the Docker image. Also, the order of these layers matters, especially for build optimization.

Make your life easy: use the Dockerfile generator

I’m going to cheat a little and tell you upfront that while having a stronger understanding of Dockerfile syntax is incredibly useful, there is an easier way (at least for JavaScript devs!), and that’s using Fly.io’s Dockerfile generator.

Using it is as simple as this:

$ npx @flydotio/dockerfile@latest
$ npx dockerfile

The package can be used with both npm and bun (you can use bunx instead of npx to run the script with bun). There are extra parameters for tweaking the Dockerfile as needed; be sure to check out the README for more details.

The Anatomy of a Dockerfile

Today we’ll be dissecting the Dockerfile for a Next.JS app as it covers all of the different ways you can use Dockerfiles productively. This will help explain the different parts of a Dockerfile even if you aren’t working on a Next.js app.

Here’s the Dockerfile we’ll be stepping through.

 # syntax = docker/dockerfile:1
# Adjust NODE_VERSION as desired
ARG NODE_VERSION=20.9.0
FROM node:${NODE_VERSION}-slim AS base
LABEL fly_launch_runtime="Next.js"
# Next.js app lives here
WORKDIR /app
# Set production environment
ENV NODE_ENV="production"
# Throw-away build stage to reduce size of final image
FROM base AS build
# Install packages needed to build node modules
RUN apt-get update -qq && \
 apt-get install -y build-essential pkg-config python-is-python3
# Install node modules
COPY --link package-lock.json package.json ./
RUN npm ci --include=dev
# Copy application code
COPY --link . .
# Build application
RUN npm run build
# Remove development dependencies
RUN npm prune --omit=dev
# Final stage for app image
FROM base
# Copy built application
COPY --from=build /app /app
# Start the server by default, this can be overwritten at runtime
EXPOSE 3000
CMD [ "npm", "run", "start" ]

 

This might seem like a lot of steps. But there are reasons for every line, and by the end of this post, you’ll understand what each one does and why it’s used.

Let’s start by taking a high-level overview. Our Dockerfile can be broken into three stages:

Set up our base image (spoilers: it’s just Node)
Build the application
Add our app code to our original base image

You’ll notice that each of these stages starts with a FROM statement, which sets a base image. FROM statements are used to set a base image, and there are a few things to note about them:

Every Dockerfile must contain at least one FROM instruction
It’s possible to have more than one FROM instruction
The last FROM instruction always wins* – And by wins, I mean used in the final image. Everything before it gets tossed out

The reason you might want to have more than one FROM statement is to optimize the size of your final image. This brings us to an important topic for Dockerfile construction: multi-stage builds.

*This behavior can be overridden when deploying your app with fly deploy —build-target=<specific target>

Multi-stage builds: what they are and why we use them

Using multiple FROM statements in our Dockerfiles allows us to break up our build process into chunks and ultimately keep our final image as small as possible.

To give an analogy, let’s pretend you’re making a batch of vegetable stock. It’s dead simple: simmer a bunch of veggie scraps in water for an hour or so, and voila! You have stock. Now, as you might expect, you have to strain out the vegetables at the end; otherwise, you just made weird soup. But! Just because the end product doesn’t contain any vegetables doesn’t mean they weren’t vital to the process.

That’s the main advantage of multi-stage Docker builds. You borrow what you need from different images to do important work and use the result in your final image, tossing out the rest. The smaller your image, the faster your app starts.

Now that we have a high-level overview of the overall flow of the Docker build, here’s what happens at each stage.

Stage 1: `base`

ARG

ARG NODE_VERSION=20.9.0

We start our file by defining which version of Node (or Bun! Or anything else) we’d like to use. Simple enough, but what exactly is that ARG command?

In Dockerfiles, there are two ways of setting variables:

ARG - These are used to set build time variables. As you might expect, these variables are available at build time (but NOT runtime)
ENV - These variables become available to your app at both build and runtime

Do not store sensitive data in your Dockerfile. They are safe to use for things like NODE_VERSION or NODE_ENV, but things like tokens, database URLs, or other secrets should be handled differently.

For handling build-time secrets, you’ll want to mount them using the RUN instruction. You can do this using the @flydotio/dockerfile package mentioned earlier, and then, when you deploy to Fly.io, set your build secret’s value (second command):

 $ npx dockerfile --mount-secret=MY_SECRET
$ fly deploy --build-secret MY_SECRET=<value>

For handling runtime secrets, these should be kept out of your Dockerfile and instead set with the following command:

 $ fly secrets set SECRET_PASSWORD=<value>

 

These secrets are exposed as environment variables when your application runs in production.

FROM

 FROM node:${NODE_VERSION}-slim as base

 

The FROM instruction sets the base image on top of which all subsequent instructions are run. In our case, node is the name of the image and :<version>-slim is a tag that’s used to denote a specific version of the base image.

When it comes to tags, here’s what the official documentation for our node image has to say:

Some of these tags may have names like bookworm, bullseye, or buster in them. These are the suite code names for releases of Debian and indicate which release the image is based on.

SOURCE: https://hub.docker.com/_/node/

How do I know what Debian release my app needs to use?

For most applications using Node or Bun, we suggest starting with the -slim variant. This takes the most recent version of Debian and strips out everything that you don’t need. If you actually do need something that was stripped out, you can add it back later to your build stage using apt-get (something we’ll cover in the build stage section).

LABEL

LABEL fly_launch_runtime="Next.js"

LABEL lets you set arbitrary key-value metadata for your Docker images and containers. It allows you to annotate whatever you want should that information be useful for your automation. This is a Fly.io specific label used by our frameworks team to track commonly used frameworks so we know what to prioritize when working on new features. It’s technically optional, but it really helps us cater to the needs of your preferred framework! 😄

WORKDIR

WORKDIR /app

The WORKDIR instruction sets the current working directory of any subsequent RUN, COPY, and ADD statements. This is where your application code will be built, and it is also the folder that gets deployed into production.

ENV

ENV NODE_ENV="production"

The ENV instruction sets environment variables that are available during both build time and runtime.

Remember, your Dockerfile is source code. Source code must never contain secret information. If you need to set secret information as an environment variable, use Fly.io secrets:

 $ fly secrets set SECRET_KEY=<value>

 

As stated previously in the section above about ARGs, the ENV` instruction is used to set environment variables that will be available during both the build and runtime. For setting sensitive data or secrets, please instead set your environment variables like so:

 $ fly secrets set SECRET_KEY=<value>

 

Stage 2: `build`

As we discussed earlier, every time you encounter a FROM statement, you know you’ve reached a new stage in a Docker build. Let’s take a look at our Dockerfile’s second stage.

FROM _ AS __

 FROM base AS build

 

This FROM...AS... signifies the start of our second stage. If you remember, our first stage began with node:<version>-slim which we named base. Now in stage 2, we’re making a copy of base and naming it build. From here on out, anything done to build will not affect the original base. You’ll see later that this allows us to cherry-pick only the bits we want to keep from build and toss the rest.

RUN

 RUN apt-get update -qq \
 && apt-get install -y build-essential pkg-config python-is-python3

Now that we’ve established a copy of base as build, we’re going to start doing some actual build work. First, let’s understand what the RUN instruction is used for, and then we’ll talk about this apt-get command.

The RUN statement is used to run commands. Shocker, I know. But it’s worth noting that it’s not the only way to run a shell command. There are actually three common instructions used for such tasks:

RUN: Always creates a new layer, thus it’s best to chain these commands into a single instruction, just as we’ve done above with multiple apt-get commands. Generally speaking, RUN is great for the setup of application code.
ENTRYPOINT: This sets the process that is first run inside your container. This is generally NOT your web server. The default entry point is /bin/sh -c, which starts up a shell process, but can be customized with the ENTRYPOINT instruction. Anything you set with the CMD instruction will then get passed as a parameter to that shell process (such as the command for starting your server).
CMD: This instruction sets the default command that’s passed to your entrypoint. This is typically where you would write the command to start your web server, for example, such as CMD ["npm", "run", "start"].

You might be wondering, what’s the difference between...

<INSTRUCTION> npm install

And using an array of strings, like so:

<INSTRUCTION> ["npm", "install"]

The difference is that when you use a string argument, Docker will run your command inside a shell (more specifically, inside /bin/sh -c). If you use a string array, it’ll run the program directly without wrapping it in a shell. In many cases, this doesn’t matter, but sometimes it can matter in very uncommon use cases, such as when you don’t have an OS in your container image or when every kilobyte of RAM matters.

What is apt-get, and why do I need it?

The tool apt-get is used for installing and managing Debian-based Linux packages (think NPM, but for OS packages; it’s similar to homebrew on macOS). The packages we’ve included (build-essential, pkg-config, and python-is-python3) are common requirements for many JavaScript packages. Experimentation may be required to find the exact set of dependencies your application requires, but even if you think your application won’t need them, it’s safe to keep this line for future development without worrying about bloat, as these won’t be included in your final image.

COPY

COPY --link package-lock.json package.json ./

After installing any Linux package requirements, we can finally start copying over parts of our application code. The COPY instruction copies a local file in your repository to a location on your Docker image.

What is --link?

Typically, if there are new changes to the layers preceding a COPY, that COPY statement will need to be re-run. Remember, for nearly every Docker instruction, a new layer is created, and layers are the tarballs that make up our Docker image. Because these layers need to be, well, layered, a diff is run to see if there are any changes to the previous layers that might affect the current one. If there are changes to earlier layers, it will invalidate the subsequent ones.

However, by including --link, we create a new layer that does not get invalidated when changes to the preceding image are made, allowing us to cache our --link layers.

To learn more, check out this article, which includes a super helpful infographic to illustrate the difference between COPY and COPY --link.

The last lines of our build step should now feel more familiar. At this point, we’re simply installing the rest of our dependencies, copying over our application code, and shucking out all of our devDependencies so our code is ready for production.

 RUN npm ci --include=dev
# Copy application code
COPY --link . .
# Build application
RUN npm run build
# Remove development dependencies
RUN npm prune --omit=dev

 

Which now brings us to the final stage...

Stage 3: `base` + `build`

 # Final stage for app image
FROM base AS runner
# Copy built application
COPY --from=build /app /app

 

We’re in the home stretch! Since we’ve reached the final FROM in our file, we know that base is going to be the target for our final image.

COPY `--from=<target>`

You’ll notice our COPY statement includes --from=build. This is the magic of using multi-stage builds. Here, we are cherry-picking the parts from our build target and leaving anything that we don’t need for runtime behind. This keeps our final image as small as possible!

EXPOSE

 EXPOSE 3000
CMD [ "npm", "run", "start" ]

We’ve made it to the end of our Dockerfile! We talked briefly about CMD statements in the sections about RUN statements, and now we can see it in action. As mentioned previously, when starting a web service, CMD is typically the instruction used to specify our start process.

Just before our start command, however, we specify the internal port that we want our Docker container to expose using the EXPOSE instruction. The key word here is internal – for web services, the specified port gets mapped to external port 80 or 443 for accepting HTTP(S) requests.

A note when deploying to Fly.io: this internal port is also set in your fly.toml. Any port specified here will overwrite the port you set in your EXPOSE instruction:

 [http_service]
 internal_port = 8080

Conclusion

Hopefully, by now, you’re starting to feel more comfortable with your understanding of Dockerfiles.

Now, I did mention our Dockerfile generator node package at the beginning of the article, but there’s an even easier method:

$ fly launch

When deploying on Fly.io with fly launch, if a Dockerfile doesn’t already exist, we generate one for you! This guide we walked through today should make understanding and tweaking the generated Dockerfile more approachable. If you get stuck, please do reach out to us on our community forum so we can help.

Congratulations, you’ve now passed Docker on Fly.io 101. Go forth and build cool things!

Ciabatta with Garlic & Basil

2023年09月18日T00:00:00+00:00

Previously, Vanilla with Candy Sprinkles covered how you could select your own “vanilla” JS demo and sprinkle in as many options as you like. But that blog post focused on Node.js, and now that Bun 1.0 has been released it is time for an update.

We could have updated the previous article in place with a series of “for Node.js do this, for Bun do that” choices, but that would have made for a much more cumbersome experience. So instead we went with a mostly parallel article with the choices already applied.

Overall the differences are:

Bun has built in file system, web server, and websocket features that enable you to create meaningful demos with zero require or import statements.
Bun has built in support for sqlite3 that can be used without installing any additional modules
Typescript is supported without any build step needed.
Bun supports ES import statements by default, and while it also supports cjs require statements, it discourages their use.

The Bun demos that you can select show off these features. You are encouraged try both the Bun and node.js demos side-by-side and compare the source code. If you are impatient, you can find selected test results online.

Additionally, Bun aims to be faster, and these demos do seem to load faster with Bun. But beyond that, these demos aren’t computationally intensive in a way that would show off performance improvements.

Let’s get started!

Baseline requirements

What we are looking for is a cross between Hello, World! and Rosetta Code, but for a full stack application. For our purposes, the baseline is a stateful web server. Ideally one that can be deployed around the globe, and can deliver real time updates. But for now we will start small and before you know it we will have grown into the full application.

A simple application that meets these requirements is one that shows a visitors counter. A counter that starts at one, and increments each time you refresh the page, return to the page, or even open the page in another tab, window, browser, or on another machine. It looks something like this:

As previously discussed, key to deployment is a package.json file that lists all of your dependencies, optional build instructions, and how to start your application. We are going to start very simple, with no dependencies and no build process, so the package.json file will start out looking like the following:

 {
 "scripts": {
 "start": "bun server.js"
 }
}

 

Now to complete this we are going to need not only a server.js file, but also HTML, CSS, and image(s). As with some of the cooking shows you see on the television, we are going to skip ahead and pull a completed meal out of the oven. Run the following commands on a machine that has bun installed:

mkdir demo
cd demo
bunx @flydotio/bun-demo@latest

Once this command completes, you can launch the application with bun start. If you have authenticated and have flyctl installed, you can launch this application with fly launch followed by fly deploy. Should you decide to run fly launch, consider saying yes to deploying a postgres and redis database as we will be using them later.

You can play with this right now.

Don’t have Bun installed or a fly.io login? Deploy using Fly.io terminal or see our Hands-on) guide that will walk you through the steps.

Try Fly for free →

If you are running it locally, open http://localhost:3000/ in your browser. If you have deployed it on fly.io, try fly open. If you are running in a fly.io terminal, there is a handy link you can use on the left hand pane.

Now take a look at server.js. It is all of 72 lines, including blank lines and comments. In subsequent sections we show how to make it smaller using available libraries, and how to add features. But before we proceed, lets save time and keystrokes by installing the node-demo package, which we will use repeatedly to generate variations on this application:

bun add @flydotio/bun-demo --dev

Using a real template

Inside the application you can see that the HTML response is produced by reading a template file and replacing a placeholder string with the current count:

 contents = contents.replace('@@COUNT@@', count.toString())

 

While this is fine for this example, larger projects would be better served with a real template. bun-demo supports two such templating engines at the moment: ejs and mustache. Select your favorite, or switch back and forth:

bunx bun-demo --ejs

and

bunx bun-demo --mustache

In either case, this script will detect what changes need to be made, give you the option to show a diff of the changes, and to accept or reject the changes. This leads us to the second option: --force that will automatically apply the changes without prompting:

bunx bun-demo --ejs --force

Relaunch your application locally using bun start or redeploy it remotely using fly deploy.

A more substantial change

While Bun.server provides the means for you to create a capable HTTP server, express makes it easy to incrementally add routes, can be configured to automatically serve static files, and integration with template engines. To convert the demo to use express, run:

bunx bun-demo --express

Both ejs and mustache have integrations with express. Try switching between the two to see how they differ.

A real database

Maintaining a counter in a text file is good enough for a demo, but not suitable for production. Sqlite3 and PostgreSQL are better alternatives:

bunx bun-demo --sqlite3

and

bunx bun-demo --postgresql

Sqlite3 is great for development, and when used with litefs is great for deployment. PostgreSQL can be used in development, and currently is the best choice for production.

To run with PostgreSQL locally, you need to install and start the server and create a database. For MacOS:

brew install postgresql
brew services start postgresql
psql -U postgres -c "drop database if exists $USER;"
psql -U postgres -c "create database $USER;"
export DATABASE_URL=postgresql://$USER:$USER@localhost:5432/$USER

Be as weird as you want to be

The JavaScript ecosystem can be delightfully weird.

The next two options are frankly polarizing. People either love them or hate them. We won’t judge you.

First tailwindcss is a CSS builder that works based on parsing your class attributes in your HTML:

bunx bun-demo --tailwindcss

Next is typescript which adds type annotations:

bunx bun-demo --typescript

TypeScript should work with all of the options on this page, in many cases making use of development only @types. All of this should be handled automatically by node-demo.

Tailwind requires a build step, which can be run via bun run build. A change to the Dockerfile used to deploy is also required, which can be made using:

bunx dockerfile

@flydotio/dockerfile is actually a separate project with its own options for you to explore.

Object Relational Mappers (ORMs)

Adding databases was the first change that we’ve seen that actually makes the demo application noticeably larger, particularly with PostgreSQL once the code that handles reconnecting to the database after network failures is included. This can be handled by including still more libraries, this time Object Relational Managers (ORMs). Three popular ones:

bunx bun-demo --drizzle

and

bunx bun-demo --knex

and

bunx bun-demo --prisma

Knex runs just fine with vanilla JavaScript. Prisma can run with vanilla JavaScript, but works better with TypeScript. Drizzle requires TypeScript.

Prisma and Drizzle also require a build step.

A final note: if you switch back and forth between Sqlite3 and PostgreSQL, you may get into a state where the migrations generated are for the wrong database. Simply delete the prisma or src/db/migrations directory and rerun the bunx bun-demo command to regenerate the migrations.

Real Time Updates

If you open more than one browser window or tab, each will show a different number. This can be addressed by introducing websockets:

bunx bun-demo --websocket

The server side of web sockets will be different based on whether or not you are using express. For the first time we are providing a client side script which is responsible for establishing (and reestablishing) the connection, and updating the DOM when messages are received. This is a chore, and htmx is one of the many libraries that can be used to handle this chore:

bunx bun-demo --htmx

The next problem is that if you are running multiple servers, each will manage their own pool of WebSockets so that only clients in the same pool will be notified of updates. This can be addressed by using redis:

bunx bun-demo --redis

At this point, if you are using fly.io, postgres, and redis, you can go global:

fly scale count 8 --region ams,syd,nrt,dfw

Future explorations

While we have explored alternative implementation of the previous Node demo, this only scratches the surface. Bun includes much more:

Bun has a native bundler built in that can be sued to package up client side scripts.
Bun has built in React/JSX support. This can be run both server side and client side.
Bun has a built in Jest-compatible test runner

node-demo is open source, and contains both the Node.js and Bun demos. issues, pull requests, and discussions are always welcome!

I hope you have found this blog post to be informative, and perhaps some of you will use this information to start your next application “vanilla” with your personal selection of toppings. Yummy!

Fly.io ❤️ Bun

2023年07月11日T00:00:00+00:00

Bun 1.0 comes out September 7th. Fly.io is making preparations.

Previously, we stated that Fly.io ❤️ JS, and we understandably started with Node.js. While that work is ongoing, it makes sense to start expanding to other runtimes.

Bun is the obvious next choice given it aims for complete Node.js API compatibility.

Starting with flyctl version 0.1.54 and @flydotio/dockerfile version 0.3.3, you can launch and deploy bun applications using fly launch and fly deploy, provided:

You’ve installed bun version 0.5.3 or later
You have a package.json that meets at least one of the following conditions:
- It has a start entry in the scripts section.
- It has a module entry and specified module as the type.
- If has a main entry.

Basically, if you can run Bun’s Quickstart and Fly’s hands-on walk-through, you have all you need to deploy your application on fly.io.

We also have a sample that you can deploy.

Be forewarned that everything is beta at this point. Some issues we encountered while preparing this support:

bun install has no --prune option. Our Dockerfiles use this to remove development dependencies after running build. Of course with bun you are less likely to need a build step as TS and JSX are built in.
throwIfNoEntry is not supported in fs.statSync. fly-apps/node-demo uses that.
Programs that used readline never exit. Switching to global.prompt resolved this issue for @flydotio/dockerfile.

Undoubtedly there will be bugs in fly’s dockerfile generator too. But as Node.js and Bun share the same generator, fixes that are made for either framework will generally benefit both.

If you see a problem, start a discussion, open an issue, or create a pull request.

Vanilla with Candy Sprinkles

2023年05月18日T00:00:00+00:00

Recapping where we are to date:

There are plenty of JavaScript frameworks to choose from, and fly.io loves them all.
Pretty much all of the big name frameworks are delightfully weird.

Picking up where we left off, this blog post will describe literally dozens (and that’s actually an understatement as you will soon see) of considerably more, dare I say it, vanilla frameworks that you can assemble on your own and deploy to fly.io and elsewhere.

This can be overwhelming, so to make things easier we are going to define a baseline application that will be reimplemented to take advantage of various tools. The result will be:

Educational. Seeing a bite sized working example is a great way to learn how a tool works.
Useful starting point. Whereas large frameworks make a number of choices for you, being able to selectively include only the tools you need can provide you with a preconfigured configuration to build upon.
Debugging aid. When a large system doesn’t behave the way you want it to, being able to reproduce and debug the problems on a smaller base not only can help you quickly narrow down the problem, and also can be used as a test case for a bug report.

Let’s get started!

Baseline requirements

 {
 "scripts": {
 "start": "node server.js"
 }
}

 

mkdir demo
cd demo
npx --yes @flydotio/node-demo@latest

Once this command completes, you can launch the application with npm run start. If you have authenticated and have flyctl version 0.1.6 or later installed, you can launch this application with fly launch followed by fly deploy. When you run fly launch, consider saying yes to deploying a postgres and redis database as we will be using them later.

You can play with this right now.

Don’t have node installed or a fly.io login? Deploy using [Fly.io terminal](https://fly.io/terminal) or see our [Hands-on](https://fly.io/docs/hands-on/) guide that will walk you through the steps.

Try Fly for free →

npm install @flydotio/node-demo --save-dev

Starting small

If you look at the top of the server.js file you will see a number of calls to require(). This is Nodes CommonJS modules. Node also supports EMCAScript modules, which is what all the cool kids are using these days.

This requires opting in. You can let node-demo make the changes for you by running the following command:

npx node-demo --esm

This script will detect what changes need to be made, give you the option to show a diff of the changes, and to accept or reject the changes. This leads us to the second option: --force that will automatically apply the changes without prompting:

npx node-demo --esm --force

Relaunch your application locally using npm run start or redeploy it remotely using fly deploy.

Using a real template

Inside the application you can see that the HTML response is produced by reading a template file and replacing a placeholder string with the current count:

 contents = contents.replace('@@COUNT@@', count.toString());

 

While this is fine for this example, larger projects would be better served with a real template. node-demo supports two such templating engines at the moment: ejs and mustache. Select your favorite, or switch back and forth:

npx node-demo --ejs

and

npx node-demo --mustache

Be sure to add --esm if you want to continue to use import statements.

A more substantial change

While node:http provides the means for you to create a capable HTTP server, it requires you to be responsible for status codes, mime types, headers, and other protocol details. express will take care of all of this for you:

npx node-demo --express

Both ejs and mustache have integrations with express. Try switching between the two to see how they differ.

A real database

Maintaining a counter in a text file is good enough for a demo, but not suitable for production. Sqlite3 and PostgreSQL are better alternatives:

npx node-demo --sqlite3

and

npx node-demo --postgresql

Sqlite3 is great for development, and when used with litefs is great for deployment. PostgreSQL can be used in development, and currently is the best choice for production.

To run with PostgreSQL locally, you need to install and start the server and create a database. For MacOS:

brew install postgresql
brew services start postgresql
psql -U postgres -c "drop database if exists $USER;"
psql -U postgres -c "create database $USER;"
export DATABASE_URL=postgresql://$USER:$USER@localhost:5432/$USER

Be as weird as you want to be

The next two options are frankly polarizing. People either love them or hate them. We won’t judge you.

First tailwindcss is a CSS builder that works based on parsing your class attributes in your HTML:

npx node-demo --tailwindcss

Next is typescript which adds type annotations:

npx node-demo --typescript

TypeScript should work with all of the options on this page, in many cases making use of development only @types. All of this should be handled automatically by node-demo.

Both of these require a build step, which can be run via npm run build. A change to the Dockerfile used to deploy is also required, which can be made using:

npx dockerfile

dockerfile-node is actually a separate project with its own options for you to explore.

Object Relational Mappers (ORMs)

npx node-demo --drizzle

and

npx node-demo --knex

and

npx node-demo --prisma

Knex runs just fine with vanilla JavaScript. Prisma can run with vanilla JavaScript, but works better with TypeScript. Drizzle requires TypeScript.

Prisma and Drizzle also require a build step.

Real Time Updates

If you open more than one browser window or tab, each will show a different number. This can be addressed by introducing websockets:

npx node-demo --websocket

npx node-demo --htmx

npx node-demo --redis

At this point, if you are using fly.io, postgres, and redis, you can go global:

fly scale count 8 --region ams,syd,nrt,dfw

Packaging alternatives

So far, we have been using npm, but yarn and pnpm are alternatives that may be better for some use cases:

npx node-demo --yarn

and

npx node-demo --pnpm

Each package manager organizes the node_modules directory a bit differently, so for best results when switching, remove the node_modules directory before switching:

rm -rf node_modules

Windows Powershell users will want to use the following command instead:

rm -r -fo node_modules

Future explorations

While we have explored many options, this only scratches the surface. There are many alternatives to the libraries above, and many more things to explore. Examples:

React can be run server side in a number of different ways, and can be run client side using a CDN or self hosted scripts.
In addition to React, there are a number of client side libraries like Angular, Lit, SolidJS, Svelte, and Vue. Coupling this with bundlers like esbuild and rollup, perhaps in a monorepo using workspaces would make good starting points for larger projects.
I welcome alternate implementations of this demo, perhaps using decidedly non-vanilla frameworks as a starting point. I’m particularly interested in implementations that support real time updates and globally distributed replications. If we get enough, perhaps we can maintain a catalog of pointers to these implementations.
While this blog post has focused on local development and deployment on fly.io, there is no lock in here. Maintaining a catalog of pointers to blog posts that describe how to deploy this application elsewhere would be welcomed too. Again, bonus points for geographic distribution and real-time updates.

node-demo is open source, so issues, pull requests, and discussions are always welcome!

I hope you have found this blog post to be informative, and perhaps some of you will use this information to start your next application “vanilla” with your personal selection of toppings. Yummy!

The JavaScript Ecosystem is Delightfully Weird

2023年05月11日T00:00:00+00:00

Note, I’m not saying that JavaScript is weird, though it definitely is weird. But that’s not the point of this blog post.

Bear with me, instead of starting with how JavaScript ecosystem is weird, I’m going to start with why the JavaScript ecosystem is weird.

Historical Background

Less that 10 years ago, JavaScript sucked bad. It had no imports, no classes, no async, no arrow functions, no template literals, no destructuring assignment, no default parameters, no rest/spread parameters. And the environment it predominately ran in, namely the browser’s DOM, sucked too. JQuery made it suck less. It still sucked, but was — at that point in time — relatively sane.

Bundling JS to run in the browser was the first sign of weirdness. In that process you would also want to both minimize and tree shake the source, and perhaps even code split. In general the process involved reading a number of JavaScript sources as input and then producing one or more JavaScript sources as output. This meant that the code you were executing wasn’t the code you wrote. Sourcemaps helped.

Then CoffeeScript came along. Instead of writing in JavaScript, you would write in a language which was compiled into JavaScript. This is a bit different than languages like Elixir and Kotlin which compile into the same byte codes as another language, CoffeeScript actually compiles into the other language. C++ started out this way.

Then came ECMAScript 6 in 2015. JavaScript improved rapidly in the next few years. This eventually mostly displaced CoffeeScript, but presented a different problem: for a while the implementations were not keeping up so transpilers like Babel came along that compiled current and future versions of JavaScript into older versions of JavaScript that ran on supported environments. Currently esbuild is rapidly rising in popularity as a Javascript bundler/transpiler.

Along the way, emscripten came along which compiled actual machine code into a subset of JavaScript, though these days the new target for this tool is generally Wasm.

Lately the pace of innovation in JavaScript has slowed, and JavaScript implementations are doing a better job of keeping up, so you would think that the need for transpilers would be waning, particularly on the server side where there is no need for bundlers. But that’s not happening. And the reason why is an interesting story.

Nobody Writes JavaScript Any More

OK, the title above is clearly hyperbole, but I’ll describe a number of the many ways that people aren’t writing JavaScript any more.

If you write a Rails application, you write it in Ruby. If you write a Django application, you write it in Python. Phoenix, Elixir. Lavavel, PHP. Rails gets a lot of flack for doing magic using meta-programming, and Elixir has macros, but all of the above stay within the boundaries of what can be done by the language.

JavaScript, however, is different. While it nominally is standardized by EMCA TC39, if you are using a popular framework like Next.JS, Remix, or Svelte you are not coding in ECMAScript as standardized by ECMA TC39. Four examples:

Once upon a time, nearly 20 years ago, the ECMA committee standardized E4X that enabled XML to be treated as a data type. This lost favor, got deprecated and archived. Years later what once was Facebook (now Meta) had a similar need and invented JSX. It differs from E4X in that it compiles into JS.
One thing that ECMA TC39 has never standardized is type annotations. Undeterred, Microsoft did it anyway with TypeScript. It, too, compiles into JS.
Svelte has their own compiler that even deliberately misuses the JavaScript label syntax to enable marking a statement as reactive.
It doesn’t stop there. When a bundler/transpiler encounters an import statement, they don’t necessarily presume that the file being imported is JavaScript or even any of the variants mentioned above. If configured properly and you want to import a CSS or PNG file, it will happily do so for you.

I mentioned earlier that Rails gets a lot of flack for its use of meta programming. Nobody bats an eye at any of the “abuses” of the JavaScript language mentioned above. The JavaScript ecosystem is a Big Tent party.

“use server”;

The latest abuse of the bundler is by React Server Components (RSC). First demoed with express, it is now adopted by Next.js.

What “use server" and "use client" do, other than being a valid JavaScript statements that do absolutely nothing, is change the meaning of the code that follows them. This has gotten mixed reviews, but in my mind is very much in the spirit of "use strict"which also changes the meaning of the code that follows.

While JSX often compiles to JS, the Server React DOM APIs enable compilation to HTML. RSC goes a different way, and compiles into a stream of tagged JSON. This is all very transparent to you, but what it does enable is a different style of programming. One that many are comparing to PHP and even Rails:

It is not clear to me whether these comparisons are meant in a positive way, but I will say that from my perspective it is a very good thing.

From a fly.io perspective, RSC enabling an Update (Refetch) Sequence is very much of interest. We’ve always been especially shiny for frameworks that benefit from geographic distribution, like Elixir’s LiveView, Laravel’s Livewire and Ruby on Rail’s Hotwire. We want those kinds of frameworks to succeed, because the better they do, the more valuable we are. Now we can add React’s RSC to that list.

Returning to the topic at hand, the fact that such a feature is only made possible through cooperation with bundlers — a statement tantamount to saying a change to the JavaScript language itself — is profound and, dare I say it, delightful.

Another Dimension

Dan Abramov gave a talk at RemixConf entitled React from Another Dimension:

In Dan’s talk he imagines an alternate universe in which React was first implemented in the late 90s on the server and still managed to converge to where it is today. During the talk he launches a Windows 95 emulator and runs Internet Explorer (specifically, IE6) with React. He even manages to get nine out of ten steps working using that operating system and browser combination.

The mind bending parts of this presentation are where he first utilizes use server to implement a client side form action, and then later launches a client side alert from the server using use client.

And he closes by saying that this requires new generation routers and new generation bundlers.

And to think all of this is made possible by the fact that the JavaScript you write not only isn’t the JavaScript you run, but under closer examination isn’t even JavaScript at all.

Fly.io ❤️ JS

2023年04月24日T00:00:00+00:00

Fly.io is a great place to run fullstack applications. For most programming languages, there is a defacto default fullstack framework. For Ruby, there is Rails. For Elixir, there is Phoenix. For PHP there is Laravel. For Python, there is Django.

If you don’t know where to look, Node.js appears to be a mess. For starters there are plenty of js frameworks to choose from. Then there are three different package managers. Not to mention that Typescript as an alternative to JavaScript. And if that is not bad enough Bun and Deno are providing alternatives to Node itself.

The result is predictable. Fly.io has a number of community contributed templates for a small number of Node frameworks. Some have had more attention than others.

It is time to clean up the mess.

`package.json` enters the chat

The key sentence in the preceding section starts with If you don’t know where to look. The right place to start is package.json. It tells you what dependencies need to be installed. For most frameworks, it tells you how to start the web server. And if there is a build step. And if there are any development dependencies that may be needed to run the build, and removed prior to deployment.

Given this knowledge, a baseline Dockerfile can be built for any framework that follows these conventions. Handling different package managers can be accomplished by looking for yarn.lock and pnpm-lock.yaml files. TypeScript is a devDependency and handled by the build step. While Deno projects don’t typically have package.json files, some bun projects do.

The dockerfile-node project endeavors to do exactly that:

npx @flydotio/dockerfile

This will create (or replace!) your existing Dockerfile, as well as ensure that you have a .dockerignore file, and optionally may create a docker-entrypoint script. You can run with this Dockerfile locally, or use it to deploy on your favorite cloud provider. For Fly.io, you would get started by running:

fly launch --dockerfile Dockerfile

The --dockerfile parameter is needed to tell fly launch to use your Dockerfile rather than trying to generate a new one.

Of course, if you prefer to run your application on Google Cloud Run, Amazon ECS, MRSK, or even locally, you are welcome to do so.

You can play with this right now.

Deploy using [Fly.io terminal](https://fly.io/terminal) or see our [Hands-on](https://fly.io/docs/hands-on/) guide that will walk you through the steps.

Try Fly for free →

Devils in the details

Not all frameworks are alike.

Some will, by default, start servers that only process requests that come from the localhost. That, of course, is entirely unsatisfactory.

Some require extra steps, for example applications that make use of Prisma.

One (and I won’t mention the name) actually lists the package needed to run the production server as a development only dependency.

Fortunately, ejs templates can include if statements and/or make use of computed variables that customize the Dockerfiles produced.

As a starter set, I’ve got templates working for the following frameworks: Express, Fastify, Gatsby, Nest, Next, Nuxt, and Remix. At the moment, I’ve been focusing on breadth vs depth, so what I have working may not be able to handle much more than the splash screen, but my experience is that getting that far is often the hardest part, after that point you have all the scaffolding in place and can focus on any specific issue that may come up.

Those are the successes so far. Here’s a list of frameworks that are still being worked on, along with the current blocking issue:

tRPC: Access to the Postgres database is required during the build step. Worst case, we do the build step during the deployment of the server, but that is suboptimal for cases where multiple servers are started.
Strapi: Needs to set secrets for JWT, session. This isn’t a problem, and already is solved for Remix deployment for fly, but at the moment goes beyond what a Dockerfile generator can do by itself.
RedwoodJS: No scripts, recommends nginx. Fly.io already has a template for Redwood, so it presumably is just a matter of work to figure out how to fit the steps required into the general purpose template. It may make sense to either encourage Redwood to add scripts to their package.json, or to add them during the dockerfile generation. If not, if statements can be used to generate Redwood-specific steps rather than generic ones.
SvelteKit: attempting to deploy results in Could not detect a supported production environment. Again, just appears to be a matter of work to add a new production environment.
KeystoneJS: at build time, I’m seeing ✘ [ERROR] Could not resolve "./keystone". Works fine on development machine, so I probably just missed a step.

In the fullness of time, these will be picked off one by one. This code is all open source, so everybody with an interest in a particular framework can contribute via issues and pull requests. Interest and participation will definitely affect prioritization of this work.

Futures

Once this script has a little bit of exposure to real world usage, it will replace the existing flyctl scanners, much in the way that dockerfile-rails is the basis for the Dockerfiles produced for Rails applications with Fly.io. At which point, usage will be as simple as fly launch.

Integration with fly launch will also enable thing like setting of secrets, defining volumes, launching of databases, and defining health checks as part of the workflow.

This package will also be designed to be re-run and accept arguments which will customize the Dockerfile produced. Peruse the usage for dockerfile-rails to see examples of the types of customizations possible. Some highlights:

--cache - use build caching to speed up builds
--swap=n - allocate swap space enabling running of larger applications on memory constrained VMs.
--compose - generate a docker-compose.yml file

The scanner will also be able to do things like detect the inclusion of puppeteer and automatically install and configure Chrome/Chromium. This is already being done for Rails applications today.

Another thing already being done for Rails applications is to run the web server as a non-root user for security reasons. Repeating this for Node.js will require knowledge of what files the application is expected to write to and which are expected to be read-only. This knowledge is necessarily framework specific, and may not be possible for minimal and general purpose frameworks like express.

Got Feedback?

If you have questions, comments, or concerns, let us know!

If they are even vaguely Fly.io related, feel free to use our community forum. Otherwise, start a discussion on GitHub.

And to those that wish to contribute, perhaps to make support for their favorite framework(s) better…. let’s do this!

The JavaScript Journal

Launching a Remix app with Postgres using Prisma

Okay, so what does this look like in action?

Our Application

Step 1: Flyctl

Step 2: Celebrate

But what if I want managed Postgres?

Using WebSockets with Next.js on Fly.io

Demystifying WebSockets

The Challenge of WebSockets on Next.js

Building a Next.js App with WebSockets

Creating the custom server

Adding the client-side code

Deploying our chat app to Fly.io

Conclusion

Build a file sharing service without making your brain hurt

Building Soar

Step 0: Setting up a SvelteKit project

Step 1: Uploading files to Tigris

S3 Client

Upload UI

And on the server…

Step 2: Retrieving files from Tigris and displaying them to the user

Step 3: Where’s the rest of the code?

What comes next

Multi-tenant apps with single-tenant SQLite databases in global Tigris buckets

Tigris setup

Node.js app with SQLite

Store the tenant database file in Tigris!

The big thing #1: deploy to Fly.io

The big thing #2: multi-tenancy with fly-replay

Conclusion

Building a Remix app locally with Docker

Create a new Remix app

Deploy to Fly.io

What is Docker Compose and why do I need it?

Docker Compose for local development

Making local changes available

Using an anonymous volume for node_modules

Live reload changes on non-Vite Remix apps

Conclusion

FLAME for JavaScript: Rethinking Serverless

What is FLAME?

What are Machines on Fly.io?

FLAME in vanilla, no-build JavaScript

Overview

The Files

Limitations of FLAME in JavaScript

Using FLAME in a JavaScript framework

Cold starts & pooling

Autoscaling for request queuing

Conclusion

Demystifying Docker for JavaScript

A quick primer on Docker vocabulary

Make your life easy: use the Dockerfile generator

The Anatomy of a Dockerfile

Multi-stage builds: what they are and why we use them

Stage 1: base

ARG

FROM

LABEL

WORKDIR

ENV

Stage 2: build

FROM ___ AS ____

RUN

What is apt-get, and why do I need it?

COPY

Stage 3: base + build

COPY --from=<target>

EXPOSE

Conclusion

Ciabatta with Garlic & Basil

Baseline requirements

You can play with this right now.

Using a real template

A more substantial change

A real database

Be as weird as you want to be

Object Relational Mappers (ORMs)

The big thing #2: multi-tenancy with `fly-replay`

Using an anonymous volume for `node_modules`

Stage 1: `base`

Stage 2: `build`

FROM _ AS __

Stage 3: `base` + `build`

COPY `--from=<target>`

`package.json` enters the chat