93 lines
3.7 KiB
Markdown
93 lines
3.7 KiB
Markdown
# Deploy Documentation to Production with Git Hooks
|
|
|
|
Git Hooks are used to update the production deployment of the `peach-devdocs` Git book, located at [docs.peachcloud.org](https://docs.peachcloud.org). This document outlines the way in which this semi-automated process is setup and utilised.
|
|
|
|
The foundational reference used for this process is the Digital Ocean guide: [How To Use Git Hooks To Automate Development and Deployment Tasks](https://www.digitalocean.com/community/tutorials/how-to-use-git-hooks-to-automate-development-and-deployment-tasks).
|
|
|
|
-----
|
|
|
|
Assuming the `peach-devdocs` repo has already been cloned to the developer's local machine, the next step is to login to the remote server (where the documentation will be hosted) and create an empty Git repository:
|
|
|
|
```bash
|
|
mkdir ~/devdocs_bare
|
|
cd ~/devdocs_bare
|
|
git init --bare
|
|
```
|
|
|
|
The `devdocs_bare` directory now contains all the files one would usually find in the `.git` directory of an initialized repository.
|
|
|
|
Next, create a second directory which will hold the files and assets needed to build the documentation Git book:
|
|
|
|
```bash
|
|
mkdir ~/devdocs_build
|
|
```
|
|
|
|
Ensure the correct permissions are set to allow modifying the web root of the production documentation directory:
|
|
|
|
```bash
|
|
sudo chown -R `whoami`:`id -gn` /var/www/docs.peachcloud.org/html
|
|
```
|
|
|
|
Now the Git hook post-receive script can be created. This script is executed after the `peach-devdocs` repository has been pushed-to from the local instance of the repository. It contains the primary logic of the automation process.
|
|
|
|
Move into the `devdocs_bare` directory and create the hooks script:
|
|
|
|
```bash
|
|
cd ~/devdocs_bare
|
|
vim hooks/post-receive
|
|
```
|
|
|
|
Add the following text to the script:
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
while read oldrev newrev ref
|
|
do
|
|
if [[ $ref =~ .*/master$ ]];
|
|
then
|
|
echo "Master ref received. Deploying master branch to build directory..."
|
|
git --work-tree=/home/glyph/devdocs_build --git-dir=/home/glyph/devdocs_bare checkout -f
|
|
echo "Building docs and deploying to production..."
|
|
mdbook build /home/glyph/devdocs_build --dest-dir /var/www/docs.peachcloud.org/html
|
|
else
|
|
echo "Ref $ref successfully received. Doing nothing: only the master branch may be deployed on this server."
|
|
fi
|
|
done
|
|
```
|
|
|
|
In brief, the script clones the latest documentation code to the `devdocs_build` directory, builds it, and copies the resulting book to the web directory.
|
|
|
|
The automated build and deployment process can now be initiated from the developer's local machine. First, the production server is added as a remote, then the push is made:
|
|
|
|
```bash
|
|
cd peach-devdocs
|
|
git remote add production user@server_ip:devdocs_bare
|
|
git push production master
|
|
```
|
|
|
|
Git will request the SSH key in order to push to the server. In the case of `peach-devdocs`, @glyph holds the key. The exact command he uses to push is:
|
|
|
|
```bash
|
|
GIT_SSH_COMMAND='ssh -i ~/.ssh/digiocean/id_rsa -o IdentitiesOnly=yes' git push production master
|
|
```
|
|
|
|
If successful, the command output should look something like the following:
|
|
|
|
```bash
|
|
Counting objects: 269, done.
|
|
Delta compression using up to 4 threads.
|
|
Compressing objects: 100% (252/252), done.
|
|
Writing objects: 100% (269/269), 382.90 KiB | 0 bytes/s, done.
|
|
Total 269 (delta 133), reused 0 (delta 0)
|
|
remote: Master ref received. Deploying master branch to build directory...
|
|
remote: Building docs and deploying to production...
|
|
remote: 2020-10-22 10:23:34 [INFO] (mdbook::book): Book building has started
|
|
remote: 2020-10-22 10:23:34 [INFO] (mdbook::book): Running the html backend
|
|
To 46.101.172.118:devdocs_bare
|
|
* [new branch] master -> master
|
|
```
|
|
|
|
As can be seen, the `echo` commands from the `hooks/post-receive` script appear in the local terminal output.
|
|
|
|
The `docs.peachcloud.org` documentation Git book is now up-to-date.
|