a fistful of drones
Using drone in the tildeverse, part 2
This is a mirror of https://www.tildegit.org/terris/susbstation/substation-drone/, explaining a similar web deployment using mkdocs and drone.
terris research substation deployment details
The repository for these pages lives at https://www.tildegit.org/terris/susbstation/ and it is structured so that it contains the files that mkdocs will use to build the site. the build directory is listed in the .gitignore file of the repository to keep them from being kept in the repository.
The terris research substation pages uses
mkdocs^[installed locally on ~team] to build the
site from markdown files. mkdocs generates a basic
mkdocs.yml file when it is
used to begin building a site, and the relevant mkdocs configuration
in the repository, but mkdocs usage is not covered here.
As is discussed in issue 3 of the
tilde zine, this repository is deployed as a website using a drone pipeline
that clones the repository into a workspace (somewhere in the
directory on ~team), and there it runs
mkdocs build to build the site from
the markdown source, and then it copies the built
site/ subdirectory to
/home/terris/public_html/. Below is the annotated drone configuration for
--- kind: pipeline type: ssh name: ssh-build-deploy server: host: from_secret: substationhost user: from_secret: scp_username ssh_key: from_secret: ssh_key
This beginning part of the yaml configuration designates for drone an ssh
ssh-build-deploy. the name is arbitrary but it shows up in drone's web
interface when you look at the status of your drone builds.
An ssh runner pipeline^[there are different runners and different kinds of pipelines, these can be researched further at drone's main documentation pages (https://docs.drone.io/configure/pipeline/) ] will ssh into the server host (stored via drone's web interface in the settings for the repository) as the specified user account, using the provided ssh key. See part 1 for more details about secrets in your drone configuration.
The names of the secrets variables are arbitrary, and
scp_username is just an
inelegant artifact for a more civili...a remnant from a previous attempt to use
an scp runner to just copy the built artifacts to the deployment webspace, but
this would have required building the site before commiting and pushing any
changes to the repository, inflating the repository size, and needlessly
tracking more files than is necessary. Some use-cases might require just this
thing, but not this one.
clone: disable: false
This section is equivalent to the default setting, which has drone clone your repository into a workspace where it can do things with the code in your repository. It is here just to explicitly demonstrate how drone handles your source repository.
steps: - name: mkdocs build&deploy commands: - mkdocs build - scp -r substation/ /home/terris/public_html/
The 2 steps outlined here are what actually build the tilde research substation
pages using mkdocs, and copy the built site subdirectory (
substation/) to the
These first step that drone takes is to clone the repository to a workspace as
shown in the previous code block, and then the commands in this codeblock above
take place in the workspace, with the cloned repository as the current working
directory. The first command builds the substation pages using mkdocs (the
mkdocs configuration already exists in the repository), converting written
markdown files in the
docs_dir subdirectory (mkdocs defaults to
html in the
site_dir subdirectory (mkdocs defaults to
site/ but this site's
configuration has it as
The second command in the above steps copies the
site_dir and its contents to
/home/terris/public_html/ overwriting any files that already exist in
/home/terris/public_html/substation/ and probably not doing anything to
remove files that have been removed from the repository and are no longer being
built as part of the set of pages. This behavior can be changed by adding a
command between those listed above:
- rm -fr /home/terris/public_html/substation.
In fact, that might be a good idea, since I had some trouble with publishing this very document after some changes to the mkdocs configuration in the repository.
trigger: branch: - master event: - push ...
The trigger configuration listed here differs from that used for the tildeverse zine as described in issue 3 and in this case, both branch and master triggers are listed. In order for drone to do anything with this repository, both conditions must be true:
- a push event to the repository
- a master branch change to the repository
Functionally, this means that in order for drone to rebuild and deploy the terris research substation pages, a push event must happen to the master branch of the repository. This might allow me to play around with other branches without having the site be constantly rebuilt.
Building and deploying
Since these pages live mostly in their repository, they are built and deployed by drone, and after making changes to the markdown sources, I can deploy them with the following common git commands in the directory where the local copy of the repository lives:
- git add .
- git commit -m "Turn and face the strange / Ch-ch-changes..."
- git push