diff --git a/README.md b/README.md index ee25036..dbfbd78 100644 --- a/README.md +++ b/README.md @@ -10,4 +10,4 @@ ## Description of mkdocs setup and drone deployment setup -> see [https://terris.tilde.team/substation/substation-drone/](https://terris.tilde.team/substation/substation-drone/) for details about deploying this repository. +> see [https://terris.tilde.team/substation/substation-drone/](https://terris.tilde.team/substation/substation-drone/) for details about deploying this repository. Or, whatever, once i find the actual link to it after fighting with mkdocs. diff --git a/docs/substation-drone.md b/docs/substation-drone.md new file mode 100644 index 0000000..83b0647 --- /dev/null +++ b/docs/substation-drone.md @@ -0,0 +1,138 @@ +# 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`. + +``` + 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 commit -a -m "Turn and face the strange / Ch-ch-changes..." +* git push + +