From 4ec3dd431f992d51274e20db2849c5a6cd885410 Mon Sep 17 00:00:00 2001 From: mycognosist Date: Fri, 23 Oct 2020 10:53:15 +0100 Subject: [PATCH 1/4] Add summary of Git hook deployment setup and usage for production --- GITHOOK_DEPLOYMENT.md | 91 +++++++++++++++++++++++++++++++++++++++++++ README.md | 8 +++- 2 files changed, 97 insertions(+), 2 deletions(-) create mode 100644 GITHOOK_DEPLOYMENT.md diff --git a/GITHOOK_DEPLOYMENT.md b/GITHOOK_DEPLOYMENT.md new file mode 100644 index 0000000..5243d31 --- /dev/null +++ b/GITHOOK_DEPLOYMENT.md @@ -0,0 +1,91 @@ +# 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. diff --git a/README.md b/README.md index ace412b..cd94d9e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # peach-devdocs -[![Build Status](https://travis-ci.com/peachcloud/peach-devdocs.svg?branch=master)](https://travis-ci.com/peachcloud/peach-devdocs) ![Generic badge](https://img.shields.io/badge/version-0.2.0-.svg) +[![Build Status](https://travis-ci.com/peachcloud/peach-devdocs.svg?branch=master)](https://travis-ci.com/peachcloud/peach-devdocs) ![Generic badge](https://img.shields.io/badge/version-0.3.0-.svg) Developer documentation for [PeachCloud](https://github.com/peachcloud) in the form of a Markdown book. @@ -42,6 +42,10 @@ The PeachCloud developer documentation book is hosted at [docs.peachcloud.org](h This tutorial from Digital Ocean describes the deployment process: [How To Set Up Nginx Server Blocks (Virtual Hosts) on Ubuntu 16.04](https://www.digitalocean.com/community/tutorials/how-to-set-up-nginx-server-blocks-virtual-hosts-on-ubuntu-16-04). -### Licensing +## Production Deployment + +Deployment of the documentation book to production is automated using Git Hooks. Refer to the [GITHOOK_DEPLOYMENT.md](./GITHOOK_DEPLOYMENT.md) document for setup and usage instructions. + +## Licensing AGPL-3.0 -- 2.40.1 From df015b4b9b83e455c83abedc484b00e27f2c194b Mon Sep 17 00:00:00 2001 From: mycognosist Date: Fri, 23 Oct 2020 10:56:44 +0100 Subject: [PATCH 2/4] Fix formatting --- GITHOOK_DEPLOYMENT.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/GITHOOK_DEPLOYMENT.md b/GITHOOK_DEPLOYMENT.md index 5243d31..79e21e4 100644 --- a/GITHOOK_DEPLOYMENT.md +++ b/GITHOOK_DEPLOYMENT.md @@ -34,7 +34,8 @@ Move into the `devdocs_bare` directory and create the hooks script: ```bash cd ~/devdocs_bare -vim hooks/post-receive``` +vim hooks/post-receive +``` Add the following text to the script: -- 2.40.1 From 8090e54939b88104bb444f8503d111c797b63c47 Mon Sep 17 00:00:00 2001 From: mycognosist Date: Fri, 23 Oct 2020 10:57:56 +0100 Subject: [PATCH 3/4] Fix formatting --- GITHOOK_DEPLOYMENT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GITHOOK_DEPLOYMENT.md b/GITHOOK_DEPLOYMENT.md index 79e21e4..1a63af0 100644 --- a/GITHOOK_DEPLOYMENT.md +++ b/GITHOOK_DEPLOYMENT.md @@ -55,7 +55,7 @@ do 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._ +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: -- 2.40.1 From 5d610412e7b302c2bd706a14d3791660f1106c2f Mon Sep 17 00:00:00 2001 From: mycognosist Date: Wed, 4 Nov 2020 10:17:41 +0000 Subject: [PATCH 4/4] Move features list to introduction section and add checkboxes to denote status --- src/SUMMARY.md | 2 +- src/features.md | 117 ----------------------------------- src/introduction/features.md | 117 +++++++++++++++++++++++++++++++++++ 3 files changed, 118 insertions(+), 118 deletions(-) delete mode 100644 src/features.md create mode 100644 src/introduction/features.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 8ac7a5e..f6b9576 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -3,6 +3,7 @@ - [Introduction](./introduction.md) - [Story](./introduction/story.md) - [Design Principles](./introduction/design_principles.md) + - [Features](./introduction/features.md) - [Quick Deployment](./quick_deployment.md) - [Hardware](./hardware/index.md) - [Requirements](./hardware/requirements.md) @@ -25,6 +26,5 @@ - [Compilation](./software/compilation.md) - [Packaging](./software/packaging.md) - [Configuration](./software/configuration.md) -- [Features](./features.md) - [Contributor's Guide](./contributors_guide.md) - [Licensing](./licensing.md) diff --git a/src/features.md b/src/features.md deleted file mode 100644 index 3242043..0000000 --- a/src/features.md +++ /dev/null @@ -1,117 +0,0 @@ -# Features - -PeachCloud features can be broadly divided between device management and Scuttlebutt functionality. - -The anticipated features for the MVP release of PeachCloud are listed below. The majority of these features will be exposed via the web interface and some will also be exposed via the physical interface. - -Since PeachCloud is built on a JSON-RPC microservices architecture, the APIs of the underlying system should be relatively simple for developers to interface with and extend. Please visit the documentation for individual microservices for further information. - -_Note: This is a work-in-progress. Expect changes._ - ------ - -## Scuttlebutt Features - -- Profile - - Display avatar - - Set avatar (upload file) - - Display bio - - Update bio -- Peers - - List friends - - List followers - - List follows - - List locally-connected peers - - Follow - - Unfollow - - Block - - Mute (private block) -- Invites - - Create an invite - - Text-based (hash) - - Share an invite - - Send to a peer within SSB (private message) - - Share publically within SSB (public post) - - Send via email - - Accept an invite - - Monitor an invite - - Check if the invite has been accepted - - For multi-use invites, show number of used & unused invite-slots - - Cancel an invite (_not sure if this is currently possible_) -- Blobs - - Display size of blob store (disk utilisation) - - Prune blobs - - By size - - By date - - By author - ------ - -## Device Features - -- Device status - - Hardware - - CPU usage - - Memory usage - - Storage usage - - Disk I/O - - Software - - Version info of PeachCloud, sbot, plugins - - Scripts - - Plugins - - Network - - Display network mode (AP or client) - - If AP, list connected devices - - Display current connection(s) - - Ethernet - - WiFi - - Display signal strength - - Display bandwidth usage - - Display hostname & external IP - - Display internal IP - - Logs - - Display system logs - - Errors - - List errors - - Report a bug / error - - Via SSB message - - Via email -- Configuration - - Access control - - Change user password - - Change administrator password - - Network - - Set network mode (AP or client) - - List available networks - - Connect to a network - - Disconnect from a network - - Forget a network - - Modify a network password - - Updates - - Check for available updates - - Download updates - - Install / apply update - - Backups - - Create backup - - Secret key - - Configuration (device settings) - - Export backup - - External storage (USB) - - List backup history - - Schedule backups - - Delete previous backups / backup history - - Alerts - - Set alerts based on CPU, memory, disk, bandwith-usage thresholds - - List previously-defined alerts - - Delete alerts - - Miscellaneous - - List current datetime - - Set datetime - - Display current timezone - - Set timezone -- Documentation - - Browse - - Scuttlebot - - Scuttlebutt - - PeachCloud - - Search diff --git a/src/introduction/features.md b/src/introduction/features.md new file mode 100644 index 0000000..a086334 --- /dev/null +++ b/src/introduction/features.md @@ -0,0 +1,117 @@ +# Features + +PeachCloud features can be broadly divided between device management and Scuttlebutt functionality. + +The anticipated features for the MVP release of PeachCloud are listed below. The majority of these features will be exposed via the web interface and some will also be exposed via the physical interface. + +Since PeachCloud is built on a JSON-RPC microservices architecture, the APIs of the underlying system should be relatively simple for developers to interface with and extend. Please visit the documentation for individual microservices for further information. + +_Note: This is a work-in-progress. Expect changes._ + +## Device Features + +- Device status + - Hardware + - [x] CPU usage + - [x] Memory usage + - [x] Storage usage + - [x] Disk I/O + - Software + - [ ] Version info of PeachCloud, sbot, plugins + - [ ] Scripts + - [ ] Plugins + - Network + - [x] Display network mode (AP or client) + - [ ] If AP, list connected devices + - [x] Display current connection(s) + - Ethernet + - WiFi + - [x] Display signal strength + - [x] Display bandwidth usage + - [ ] Display hostname & external IP + - [x] Display internal IP + - Logs + - [ ] Display system logs + - Errors + - [ ] List errors + - Report a bug / error + - [ ] Via SSB message + - [ ] Via email +- Configuration + - Access control + - [ ] Change user password + - [ ] Change administrator password + - Network + - [x] Set network mode (AP or client) + - [x] List available networks + - [x] Connect to a network + - [x] Disconnect from a network + - [x] Forget a network + - [x] Modify a network password + - Updates + - [ ] Check for available updates + - [ ] Download updates + - [ ] Install / apply update + - Backups + - Create backup + - [ ] Secret key + - [ ] Configuration (device settings) + - [ ] Export backup + - External storage (USB) + - [ ] List backup history + - [ ] Schedule backups + - [ ] Delete previous backups / backup history + - Alerts + - Set alerts based on: + - [ ] CPU + - [ ] Memory + - [ ] Disk + - [x] Bandwith-usage + - [ ] List previously-defined alerts + - [ ] Reset alerts + - Miscellaneous + - [ ] List current datetime + - [ ] Set datetime + - [ ] Display current timezone + - [ ] Set timezone +- Documentation + - Browse + - [ ] Scuttlebot + - [ ] Scuttlebutt + - [ ] PeachCloud + - Search + +## Scuttlebutt Features + +- Profile + - [ ] Display avatar + - [ ] Set avatar (upload file) + - [ ] Display bio + - [ ] Update bio +- Peers + - [ ] List friends + - [ ] List followers + - [ ] List follows + - [ ] List locally-connected peers + - [ ] Follow + - [ ] Unfollow + - [ ] Block + - [ ] Mute (private block) +- Invites + - [ ] Create an invite + - Text-based (hash) + - [ ] Share an invite + - [ ] Send to a peer within SSB (private message) + - [ ] Share publically within SSB (public post) + - [ ] Send via email + - [ ] Accept an invite + - [ ] Monitor an invite + - [ ] Check if the invite has been accepted + - [ ] For multi-use invites, show number of used & unused invite-slots + - [ ] Cancel an invite (_not sure if this is currently possible_) +- Blobs + - [ ] Display size of blob store (disk utilisation) + - Prune blobs + - [ ] By size + - [ ] By date + - [ ] By author -- 2.40.1