From e76d40c0881d60fae430cf01556a759451ebff0d Mon Sep 17 00:00:00 2001
From: ctmbl <mabileau.clement@gmail.com>
Date: Thu, 9 Nov 2023 21:37:41 +0100
Subject: [PATCH] Improve README

---
 README.md | 36 +++++++++++++++++++++++++++---------
 1 file changed, 27 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 66b4d78..a5f903f 100644
--- a/README.md
+++ b/README.md
@@ -2,24 +2,26 @@
 
 ## TODO
 Non-exhaustive TODO-list:
- - [ ] print a `lastUpdate` or `updated` date param on posts
- - [ ] show posts which `draft` param is `true` in dev mode (if possible)
- - [ ] add a comments engine
  - [X] write a workflow that prevents merging if website doesn't build
- - [ ] write a workflow warning if the new content is still draft
  - [X] fix nginx.conf and run_nginx.sh properly
+ - [X] Add automatic deployment on push to src/**
+ - [ ] write a workflow warning if the new content is still draft
  - [ ] add https
+ - [ ] add posts from previous website
+ - [ ] add a comments engine
+ - [ ] print a `lastUpdate` or `updated` date param on posts
+ - [ ] show posts which `draft` param is `true` in dev mode (if possible)
  - [ ] check when building (with builder target) that git submodule is updated
 
 ## Deployment
 
 ### Production
 
-Create the blog directory, **it must be writable by the user that will write to it: you, builder target, CI user...**
+Create the blog directory, **it must be writable by users that will write to it: you, builder target, CI user...**
 ```sh
 mkdir build/blog
-chmown <make it writable by the appropriate user/group>
 chmod <make it writable by the appropriate user/group>
+chmown <make it owned by the appropriate user/group>
 ```
 
 > you should check first the consistency of the server name (iscsc.fr/localhost) in those files: `nginx.conf`, ...
@@ -30,7 +32,7 @@ docker compose build blog
 docker compose up --detach blog
 ```
 
-> Note: before the next step make sure when cloning the repository you also updated the git submodule!
+> Note: before the next step make sure that when cloning the repository you also updated the git submodule!
 
 Then builds the static website, `./build/blog` is a volume shared with both containers so 
 building the website will automatically "update" it for nginx.
@@ -38,9 +40,25 @@ building the website will automatically "update" it for nginx.
 docker compose up builder
 ```
 
+### Automatic deployment
+The repository contains a GitHub Actions which automatically:
+ 1. **builds the website**: allow to check that nothing is broken, publish an artifact which can be downloaded or reused
+ 2. IF push to main AND `src/*` modified, **deploys the build**: download the artifact, create and setup ssh key, send build to server through ssh (with `rsync`)
+
+This requires a server (a VPS) ready to receive the build *(and to be useful, running a http server serving this build)*, and, of course, to set some mandatory GitHub secrets (ssh key, CI username on server, path,...).
+
+
+Sources I used:
+- [Scott W. Harden's tuto](https://swharden.com/blog/2022-03-20-github-actions-hugo/)
+- [HUGO deocumentation](https://gohugo.io/hosting-and-deployment/deployment-with-rsync/)
+- [GitHub Actions documentation](https://docs.github.com/en/actions/learn-github-actions/contexts#steps-context)
+
 ### Development
 
-```
+```sh
 cd src
 hugo server
-```
\ No newline at end of file
+```
+> it requires `hugo` installed locally!
+This will build sources and start a basic development server that listens on http://localhost:1313.  
+The HUGO server automatically watches sources, so if you create a new post while it's running it will automatically rebuild the website and serve the new post.