From 9ea6aca12fefc2d18bcbeff08a7bf28790036086 Mon Sep 17 00:00:00 2001 From: ClementMabileau Date: Sun, 22 Sep 2024 15:47:10 +0200 Subject: [PATCH] Improve README.md (#52) * TODO pour cette branche * Add NOTES * Improve renew certificates instructions * Improve and adapt README.md to #53 * Add the Feature section * Add required secret list * Add links to features * Improve deployment instructions and add contibuting * add a toc --- README.md | 120 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 84 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index c6d6892..084ba47 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,34 @@ # blog.iscsc.fr: a blog built with HUGO framework -## TODO -Non-exhaustive TODO-list: - - [X] write a workflow that prevents merging if website doesn't build - - [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 - - [X] add https - - [X] add posts from previous website - - [ ] add a comments engine - - [X] fix baseUrl and "iScsc" sidebar brand name not redirecting - - [ ] print a `lastUpdate` or `updated` date param on posts - - [X] show posts which `draft` param is `true` in dev mode (if possible) - - [ ] check when building (with builder target) that git submodule is updated - - -## Features -- renders emojis https://emojibase.dev/shortcodes/? - +**Table of content**: +- [Deployment](#deployment) + - [Production](#production) + - [TL;DR](#tldr) + - [Create SSL certificates](#create-ssl-certificates) + - [Renew SSL certificates](#renew-ssl-certificates) + - [Deploy the website itself](#deploy-the-website-itself) + - [Automatic deployment](#automatic-deployment) + - [Development](#development) +- [Features](#features) + - [Incoming fetaures](#incoming) +- [Contributing](#contributing) ## Deployment ### Production -#### Create SSL certification +### TL;DR +- create SSL certificates (needed for HTTPS) +- *create* the build directory with the right permissions +- *start* the nginx web server with a docker command +- *build* the website with a docker command +- enjoy the website! + +#### Create SSL certificates To set up HTTPS, you will need valid SSL certificates. If you deploy the app for the first time, follow these instructions: -- Comment or delete the whole server section about 443 in the `nginx.conf` file. +- Comment or delete the whole server section about port 443 in the `nginx.conf` file. ```diff - server { @@ -60,49 +61,71 @@ docker compose down The certificates should have been generated in `certbot/conf/live/yourdomainname.com/`. -#### Renew SSL certification +#### Renew SSL certificates -If you just want to renew existing certificates, use: +If you just want to renew existing certificates you should use the designed script: +```bash +./scripts/renewssl.sh +``` +> Note that this script uses hardcoded absolute path designed for the iScsc VPS +If you want to here are the detailed steps: ```bash +# List existing certificates +docker compose run certbot certificates +# Renew certificates docker compose run --rm certbot renew +# Restart blog +docker compose stop blog +docker compose up --detach blog ``` #### Deploy the website itself -Create the blog/prod directory, **it must be writable by users that will write to it: you, builder target, CI user...** +- *Create* the `./build/blog/prod` and `./build/blog/dev` directory, **they must be writable by the user/group that will write to it: you, builder target, CI user...** ```sh mkdir -p build/blog/prod -chmod -chown +mkdir -p build/blog/dev +sudo chown -R : build/blog +sudo chmod -R g+w build/blog ``` -> you should check first the consistency of the server name (iscsc.fr/localhost) in those files: `nginx.conf`, ... +> you should check first the consistency of the server name (iscsc.fr/localhost) in those files: `nginx.conf`, `docker-compose.yml`, workflows in `.github/workflows` ... -Start the nginx container to serve requests: +- *Start* the nginx container to serve requests: ```sh docker compose build blog docker compose up --detach blog ``` -> Note: before the next step make sure that when cloning the repository you also updated the git submodule! +> **Note:** +> Before the next step make sure that when cloning the repository you also fetched the git submodule! -Then builds the static website, `./build/blog/prod` is a volume shared with both containers so building the website will automatically "update" it for nginx. +- *Build* the static website, `./build/blog/prod` is a volume shared with both containers so building the website will automatically "update" it for nginx. ```sh docker compose up builder ``` +After doing this last step, files might have been created with the wrong permissions/owners (it depends if you use the setgid bit, modify the builder container, and even what YOU consider being the right permissions/owners). If needed you might re-do what we've previously: +```sh +sudo chown -R : build/blog +sudo chmod -R g+w build/blog +``` + ### Automatic deployment -The repository contains a GitHub Actions which automatically: +The repository contains a GitHub Action 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,...). - +This requires a server ready to receive the build *(to be useful, it must be running an http server serving this build)*, and to set some mandatory GitHub secrets (see [`build_and_deploy.yml`](https://github.com/iScsc/blog.iscsc.fr/blob/main/.github/workflows/build_and_deploy.yml)): +- `SSH_KNOWN_HOSTS` +- `PRIVATE_SSH_KEY` +- `CI_USER_NAME` +- `REPO_PATH_ON_REMOTE` 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/) +- [HUGO documentation](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 @@ -110,11 +133,36 @@ Sources I used: > it requires `hugo` [installed](https://gohugo.io/installation/) locally! ```sh cd src -hugo server --buildDrafts --buildFuture +hugo server --buildFuture --buildDrafts --disableFastRender ``` -> `--buildFuture` is also used in production, `--buildDrafts` only in development -> `--buildExpired` can be used too +- `--buildFuture` is also used in production, `--buildDrafts` only in development +- `--buildExpired` can be used too +- `--disableFastRender` will avoid you headaches trying to debug what is really a HUGO cache problem 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. + +## Features + +- [articles](https://iscsc.fr/posts) about various subjects around computer science: security, development, network, operating systems... +- numerous useful [resources](https://iscsc.fr/resources), tools, guides, tutorials +- an [event](https://iscsc.fr/events) page to gather all relevant information about CTFs, conferences, forums... +- everyone can contribute through GitHub PRs, see our [tutorial](https://iscsc.fr/posts/publish-your-own-post/) +- renders [emojis](https://gohugo.io/quick-reference/emojis/#smileys--emotion) +- automatic build and deployment of the website on every merge + + +### Incoming + +Incoming features: +- add a club members page +- add a comment engine ([see example on poison repo](https://github.com/lukeorth/poison?tab=readme-ov-file#comments)) +- print a `lastmod` date on posts (see [`lastmod` on HUGO's doc](https://gohugo.io/content-management/front-matter/#lastmod)) + +## Contributing + +To contribute to the website **code or good-looking** feel free to open an [Issue](https://github.com/iScsc/blog.iscsc.fr/issues/new) for new features, improvements or UX/UI changes, or directly a [Pull Request](https://github.com/iScsc/blog.iscsc.fr/pulls) for bug fixes or typos. + +To contribute to the **knowledge** gathered on this website give a look at our [tutorial](https://iscsc.fr/posts/publish-your-own-post/) for new contributors 🙂 +...or directly open a [Pull Request](https://github.com/iScsc/blog.iscsc.fr/pulls) if you already know how these things work 😉 \ No newline at end of file