fisticuffs with mkdocs
continuous-integration/drone/push Build is passing
Details
continuous-integration/drone/push Build is passing
Details
This commit is contained in:
parent
9a1805cd0a
commit
9390416b1b
|
@ -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.
|
||||
|
|
|
@ -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
|
||||
|
||||
|
Loading…
Reference in New Issue