155 lines
6.1 KiB
Markdown
155 lines
6.1 KiB
Markdown
# a fistful of drones
|
|
|
|
author: [terris](https://terris.tilde.team/)
|
|
|
|
## Using drone in the tildeverse, part 2
|
|
|
|
### Another example
|
|
|
|
This is a mirror of [https://www.tildegit.org/terris/susbstation/substation-drone/](https://www.tildegit.org/terris/susbstation/substation-drone/), explaining a similar web deployment using mkdocs and drone.
|
|
|
|
## terris research substation deployment details
|
|
|
|
### repository
|
|
|
|
The repository for these pages lives at
|
|
[https://www.tildegit.org/terris/susbstation/](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](https://tildegit.org/terris/substation/src/branch/master/.gitignore)
|
|
file of the repository to keep them from being kept in the repository.
|
|
|
|
### mkdocs
|
|
|
|
The terris research substation pages uses
|
|
[mkdocs](https://www.mkdocs.org/)^[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
|
|
file](https://tildegit.org/terris/substation/src/branch/master/mkdocs.yml) is
|
|
in the repository, but mkdocs usage is not covered here.
|
|
|
|
### .drone.yml
|
|
|
|
As is discussed in [issue 3](https://zine.tildeverse.org/issue-3.html) 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 `/tmp/...`
|
|
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
|
|
this deployment:
|
|
|
|
|
|
```
|
|
---
|
|
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
|
|
runner pipeline](https://ssh-runner.docs.drone.io/configuration/overview/)
|
|
named `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](https://zine.tildeverse.org/issue-3.html) 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
|
|
[deployment webspace](https://terris.tilde.team/substation/).
|
|
|
|
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 `docs/`) to
|
|
html in the `site_dir` subdirectory (mkdocs defaults to `site/` but this site's
|
|
configuration has it as `substation/`).
|
|
|
|
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](https://zine.tildeverse.org/issue-3.html) 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](https://ssh-runner.docs.drone.io/configuration/trigger/):
|
|
|
|
* 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
|
|
|