Quick blog set-up with Quarto and Fly.io

This is a quick tip to get started to set up your own blog website, similar to my blog website https://eriklz.online.
I have set up a couple of websites with blogs using this approach, and I find it quite nice - and I hope you will find it useful as well!

The set-up here is pretty much the same as I use with my blog, and it is fairly straightforward to do.

There are a few key components needed:

• Docker Desktop, or something that is a compatible alternative
• Quarto, a technical publication system to create websites, books, documents etc from Markdown
• Fly.io, a developer-centric and friendly cloud platform
• Optional: GitHub, for version control and automating publishing of updates

Installation

Follow the installation instructions for your platform for Docker Desktop and Quarto, if you do not have them installed already.

Also, create a personal account on Fly.io, and install their flyctl command-line tool.

Set-up of website/blog content

First, if you are going to use GitHub for version control, create a repository there, let us assume it is called my-awesome-blog. It is fine to have a private repository.
You can then clone it to your local computer from the command-line, e.g.

git clone [e-mail]/myuser/my-awesome-blog.git

Change to this repository and set up a blog project using Quarto:

cd my-awesome-blog
quarto create project blog .

The quarto command will ask for the title of the blog, and then generate some initial files for a blog set-up.
You can view what the current setup looks like in the browser by running quarto preview.
This command will generate the website content, start a local web server and open up the home page in a browser.

For updating the actual content, you will need to look a bit further in the quarto documentation.
For general text and image content, it should be pretty ok to learn - quarto uses Markdown files, but has also a lot of extensions on top of the regular Markdown.

The _quarto.yml file is the file that will control the overall layout of the webpage, and individual .qmd files are essentially the Quarto Markdown files that provide content for each page.

To generate the web site content for "real" you would rather use the quarto render command.
This is what you use to generate the content to be used with further steps to deploy the blog, so you can run that and verify that it works.

The generated content will be in the directory _site.

Set-up of webserver

Next step is to set up a web server to serve the content to the real world.
For this, we use fly.io.

In the root of your project/repository, create a file Dockerfile with the following content:

FROM nginx:alpine

COPY _site /usr/share/nginx/html

We use a container image for nginx web server, and we copy the generated output from quarto, which will be in directory _site, to where web pages will be served from in nginx.

Now on the command-line, in the root directory of your project, run the command

flyctl launch

This will start a wizard to set up a server to run nginx.
If it asks to include the contents of the .gitignore file into .dockerignore, you can also answer no.
When it asks if you want to modify the configuration in fly.toml you can answer yes, and at least change the port number from 8080 to 80.

You can also change the app name, since it will generate a hostname by default that is my-awesome-blog.fly.dev for you.
(The app name will be my-awesome-blog unless that is already in use, and fly.io will generate a different app name for you)

Once the wizard has created the configuration, it will also try to deploy the web server and start it.
If that works ok, you will be able to access your blog web site on my-awesome-blog.fly.dev.

If you need to tweak the configuration, you can do that in the generated fly.toml file and run flyctl deploy to re-deploy the web server.

By default, the generated configuration will scale down to 0 machines after some idle time, and automatically start up a new machine if there is incoming traffic.
So if you are not getting much traffic, the costs will be quite low.
Fly.io even waives your bill if it is lower than $5 in a month.

So I would say it is pretty safe to start experimenting this way without worrying about runaway costs.

Version control tweaks

At this stage, you may want to commit your updates to your git repository.
Before you do that, you can add _site to your .gitignore file.

Thus you will only keep the source data in version control, not the generated result.

Optional - automate deployment on change through GitHub actions

If you have a GitHub repository, the flyctl wizard will have generated a file .github/workflows/fly-deploy.yml for you.
This include enough to essentially run flyctl deploy through GitHub actions.

However, you also want to let quarto render the web site content before deploying.
You can replace the content of this workflow file with the following content to also invoke quarto render before deployment:

name: Fly Deploy
on:
  push:
    branches:
      - main
jobs:
  deploy:
    name: Deploy app
    runs-on: ubuntu-latest
    concurrency: deploy-group    # optional: ensure only one action runs at a time
    steps:
      - uses: actions/checkout@v4
      - uses: quarto-dev/quarto-actions/setup@v2
      - uses: quarto-dev/quarto-actions/render@v2
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: flyctl deploy --remote-only
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

In the GitHub repository, you must also add a secret in the settings for the repository, FLY_API_TOKEN.
On the command-line in the project, run the following command:

flyctl tokens create deploy

Copy all the content in the output to the FLY_API_TOKEN secret in the GitHub repository.

Now any update to the main branch should trigger the workflow and re-deploy the updated website.

Custom domain and certificates

If you want to set up your own custom domain and create certificates for your awesome blog, then you need to register your domain name of choice with a domain registrar.
After that, you can go through this guide at fly.io to set up your custom domain for your website.

Final remarks

I have set up multiple websites with this approach, including blogs and online books.
For this purpose, Quarto and Fly.io have worked really well, I think.
Since the cost will essentially be 0 for low traffic, you can experiment with this type of setup without worrying too much about the cost.

You can of course publish Quarto-based material through other means as well, including GitHub pages, Netlify, etc.
For me, using fly.io has suited me very well, and their developer experience is quite nice.

I hope this information has been useful to you, and inspire to using Quarto and/or fly.io!