# 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