Adding a static site

Overview

This guide covers adding a new static site to a webserver. It assumes the webserver is already set up as per the webserver setup guide.

Adding a new site

Now the basics of the webserver are set up, let’s add a new site.

Initializing a new site

task new-static-site SITE_NAME="new-site" DOMAIN="new-site.com"

This will:

• create a new directory in ~/sites/ for the new site
• create a new .caddy config file in the sites-enabled directory (locally, and on the server)

Deploying a new site

Now we just need to send some static files to the server for it to server them.

For this, generally we’ll be working in the repository for the site that should be deployed.

In order to have access to the task commands from the webserver repository, it’s helpful to have a global Taskfile set up.

Create a ~/Taskfile.yml with the following content:

version: "3"

includes:
  web:
    taskfile: ~/path/to/webserver/Taskfile.yml
    optional: true
    dir: ~/path/to/webserver/

This will give access to the tasks from anywhere via task -g web:.... (-g for global, and web: is the prefix added because it is an included taskfile).

Now, from the respository that has a static site.

task web:deploy-static SITE_NAME="new-site" STATIC_DIR="path/to/static/files"

Where the STATIC_DIR will typically be something like static or _site etc. depending on the site generator.

Note

You can also run from anywhere and specify the PROJECT_DIR as well. E.g. from the webserver repository:

task deploy-static SITE_NAME="new-site" STATIC_DIR="path/to/static/files" PROJECT_DIR="path/to/repo"

This will copy the files to the server, run a script on the server to move the files to the /srv/www directory, and then restart the caddy server.

Updating a site

To update the site, just run the same deploy-static task again.

This process can be made even easier by adding a task in the sites repository Taskfile.

includes:
  # Include webserver task
  web:
    taskfile: ~/path/to/webserver/Taskfile.yml
    dir: ~/path/to/webserver-dir
    optional: true
    internal: true

tasks:
  deploy:
    desc: "Deploy the static site"
    cmds:
      - quarto render  # Or whatever command is needed to build the site
      - task: web:deploy-static
        vars:
          STATIC_DIR: _site
          SITE_NAME: quarto-dotfiles
          PROJECT_DIR: "{{.TASKFILE_DIR}}" # Ensures the root dir is always right even if task is called from a subdirectory

Updating automatically via GitHub Actions

Generally, it’s better to set up an automated workflow for things like deployment.

Using a template workflow

There is a template github actions workflow other-templates/github-workflows/deploy-static-site.template.yml that can be copied to the .github/workflows directory in the of the site that should automatically deploy to the webserver.

You’ll want to set up an environment to add the necessary vars and secrets (in the template it assumes a production environment). See this guide on Managing environments for deployment to learn environments.

The required secrets for the template workflow are shown below, although these will likely need to be tailored to the specific project:

• Secrets:
  • SSH_PRIVATE_KEY – A private ssh key that grants access to the webserver (obtained via the task -g web:add-ssh-key command)
  • GITHUB_TOKEN – This is set automatically by GitHub (do not set this manually)
• Vars:
  • VPS_IP – The IP address of the webserver (since the GHA runner wont have the ssh alias set up)
  • SITE_NAME – The name of the site on the webserver (same as the SITE_NAME used in other tasks)