Remotely updating a Quarto website

I maintain a couple of websites - this one, and one for a local Science group (Science at Fishbourne). The sites are built with Quarto and hosted on netlify. My workflow (see below) works well from my laptop but I wanted a way to make updates, add new articles etc while travelling and with only access to my phone. The science group website in particular needs a monthly update, based on content created by other people, that needs to happen within a few days of the last group meeting. I won’t always be at home to do that.

Update workflow

Quarto sites are a collection of markdown files, plus some YAML configuration files and any images etc. I use git for version control and have the remote repository on GitHub. When I push changes to GitHub, netlify automatically detects the change, builds the site from source, and deploys the new version. The repository only contains source files (markdown, images etc), not the built website.

On my laptop I normally either edit files with vi and use quarto preview to preview any changes, or edit files in VSCode and use the Quarto plugin to preview. Once I’m done, I commit the changes and netlify does the rest.

As well as pure text editing, I use a few additional utilities :

An exiftool script to strip sensitive EXIF metadata (GPS coordinates etc) from images
A python script to generate web previews from a URL
imagemagick for resizing and/or format converting images
I sometimes get contributions in Word or other file formats. I use pandoc to convert those directly to markdown.

So here’s a typical update:

Create and edit some markdown files. I often use existing markdown files as a starting point for new files.
Add an image that someone has sent me in an email
Add text that someone has sent me as a Word document
Download some photos from my phone and resize them
Strip sensitive metadata from the images
Create a git commit and push it to the remote repository

Travelling

I need to be able to update the sites when I’m away from home with only my iPhone. Although I could theoretically make changes directly in GitHub, that would be hard going from the phone and adding images and other attachments would be cumbersome. Even if that were manageable, I’d have no way of using the other utilities I rely on.

I wanted a more flexible option…

My solution

I have a Raspberry Pi (4B) on my home network which is permanently on. It seemed like it should be possible to do everything on there (spoiler: it is!) but there are a few things to set up to get a workable remote solution that’s usable from a phone.

Remote access to the Raspberry Pi

If you’re not already using Tailscale, you probably should be! It’s an excellent tool that builds a VPN (known as a Tailnet) between your devices and allows secure communication to and between them from anywhere - whether you are on your local network or not.

I have Tailscale installed on the Raspberry Pi, my laptop, phone, iPad, etc. Regardless of where I am, I can securely access the Raspberry Pi from any of those devices.

Install Tailscale on the Pi using curl -fsSL https://tailscale.com/install.sh | sh

Access from an iPhone

There are various terminal-type apps for the iPhone. I’ve chosen to use Termius, which has a nice interface and integrates seamlessly with Tailscale.

Termius on iPhone, accessing the Pi shell remotely over Tailscale

Termius connects to the Pi using ssh and Tailscale automatically generates ssh keys to connect between your devices. Connecting via Termius brings up an authentication dialog from Tailscale; once validated you’re in.

Termius also supports sftp which was my first solution for sending email attachments and other files to the Pi (see below).

Software setup

I’ve installed the following on the Raspberry Pi

git (probably installed by default, but otherwise sudo apt install git)
pandoc (sudo apt install pandoc)
imagemagick (sudo apt install imagemagick)
exiftool (sudo apt install exiftool)

I’ve also copied across some homemade utilities - my exiftool script that removes personal information from images, and my python script for creating web previews.

Note: I have not installed Quarto itself. The changes I make remotely are normally relatively simple so I don’t feel the need to build and validate them on the Pi. I use the production site as my test environment; I push my changes and manually inspect the site once netlify has rebuilt it. If I spot any mistakes (not normally more than a typo or two), I just fix those issues and push a second commit. I might change my mind one day and install Quarto - if I do, I’ll write an update to this post.

Note 2: There is a restriction in some versions of imagemagick that prevent it from converting PDF files (this is something I need to do). If you run in to that issue, edit /etc/ImageMagick-6/policy.xml and remove the following lines:

<!-- disable ghostscript format types -->
<policy domain="coder" rights="none" pattern="PS" />
<policy domain="coder" rights="none" pattern="PS2" />
<policy domain="coder" rights="none" pattern="PS3" />
<policy domain="coder" rights="none" pattern="EPS" />
<policy domain="coder" rights="none" pattern="PDF" />
<policy domain="coder" rights="none" pattern="XPS" />

File transfer

I need some method to transfer files from the phone to the Pi. I sometimes get sent documents and/or image files to add to the site and I routinely want to add my own pictures.

My initial solution used the sftp client built in to Termius. Since then I’ve added a Samba share so I can save to the Pi directly from the iOS Files app. Both options are described below.

Option 1: sftp

Save files / attachments / images to the phone so they are accessible with the Files app
In Termius, open a sftp session to the Pi
Navigate to the folder on the Pi you want to upload to
Select upload from the three-dots menu and select the file from from the dialog box

Option 2: Setting up a Samba share

I thought I’d try setting up a network share that could be accessed over the Tailnet.

The basic setup is straightforward:

Install samba on the Pi (sudo apt install samba samba-common-bin)
Create a directory to share. You could share your entire home directory but I opted to create a dedicated subdirectory
Add the following to the /etc/samba/smb.conf
Give your user a Samba password (sudo smbpasswd -a YOUR_USER_NAME)
Restart the Samba daemon (sudo systemctl restart smbd)

[YOUR_SHARE_NAME]
   path = /home/YOUR_USER_NAME/shared
   read only = no
   writeable = yes
   browseable = yes
   public = no
   create mask = 0775

Once I did this I could access the share from my Mac (Finder - Add network ). It gave me read/write access to the shared directory and read access to the whole home directory.

However, when I added the share to the Files app on iOS, I only had read access…. It took a while to find a solution but in the end I added the following under the [global] settings in /etc/samba/smb.conf

   vfs objects = fruit streams_xattr
   fruit:metadata = stream
   fruit:model = MacSamba
   fruit:veto_appledouble = no
   fruit:nfs_aces = no
   fruit:wipe_intentionally_left_blank_rfork = yes
   fruit:delete_empty_adfiles = yes
   fruit:posix_rename = yes

After another daemon restart, and disconnecting and reconnecting the share in Files, everything worked. There may be some redundancy in these settings but I haven’t tried to work out which ones are critical. If it ain’t broke…

In the Files app I’ve actually added two shares (Files -> three-dots -> Connect to Server) . One uses the local network address of the Pi for when I’m at home and not on the Tailnet. The other uses the Tailscale DNS name of the Pi and provides remote access via Tailscale.

Adding a network share in the iOS Files app

My remote workflow (from an iPhone)

Log on to Raspberry Pi (using Termius)
Go to the root directory of the site
git fetch / git pull to update the local copy
Make necessary changes to the markdown files
If necessary, convert any Word files to markdown with pandoc. Manually edit the output to add the Quarto metadata.
Move any images to their correct location after doing any conversion, resizing, metadata removal etc.
Stage, commit and push the changes
Review the updates on the live site. Make any changes necessary

Optional Extras

External keyboard: The workflow above works but using the on-screen keyboard can get a bit tiresome after a while, especially on a phone (it’s better on an iPad). I bought this cheap keyboard, which makes typing (and in particular manipulating text in vi) much easier. It cost me £8 on eBay. I’m sure there are better keyboards, but this is small (200mm x 115mm) and weights about 150g.

Drafts app (iPhone/iPad/Mac): I’ve started using this app to write markdown articles from scratch. Drafts shows the markdown structure while editing and also has a full preview mode. Articles can be saved as markdown files directly to the Files app, and therefore to the Samba share on the Raspberry Pi.