From 6b4efb474cb5b9d8d38a4aedbc76f8f37d980fbb Mon Sep 17 00:00:00 2001 From: Alain Reguera Delgado Date: Apr 24 2021 19:02:31 +0000 Subject: Update README.md - Add section to describe how to run jekyll build --watch inside a container managed by systemd. - Minor changes related to content markup. --- diff --git a/README.md b/README.md index 36988c1..3cac201 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ The CentOS.org website is using the following tools: - * [jekyll](https://jekyllrb.com/) 4 + * [jekyll](https://jekyllrb.com/) 4 * [bootstrap](https://getbootstrap.com/) 4. * [podman](https://podman.io) (but should work with other know containers solutions too) @@ -12,73 +12,118 @@ The CentOS.org website is using the following tools: Just ensure that you have git, podman installed on your CentOS, Fedora workstation (or any other linux distro, just showing this as example): -``` -sudo yum install slirp4netns podman git -``` + sudo yum install slirp4netns podman git ### Cloning this repo, from your forked version -You should first login with your [ACO](https://accounts.centos.org) login on https://git.centos.org, and then fork this repo (if not already done) +You should first login with your [ACO](https://accounts.centos.org) login on +https://git.centos.org, and then fork this repo (if not already done) -Once done, you'll have to clone your fork locally, and submit changes. -This section describes the steps you need to follow in order to render the -final site using jekyll in Fedora 31/CentOS 8, with rootless container. +Once done, you'll have to clone your fork locally, and submit changes. This +section describes the steps you need to follow in order to render the final +site using jekyll in Fedora 31/CentOS 8, with rootless container. Let's assume the following (so feel free to update): - * git_upstream="ssh://git@git.centos.org/forks//centos/centos.org.git" # replace with your ACO username - * git_directory="$HOME/git/" # where you'll git clone git repo + export git_upstream="ssh://git@git.centos.org/forks//centos/centos.org.git" # replace with your ACO username + export git_directory="${HOME}/git/" # where you'll git clone git repo -Let's first clone git repo and ensure that some files in container will be owned by jekyll : -``` -test -d ${git_directory} || mkdir -p ${git_directory} -pushd ${git_directory} -test -d centos.org || git clone ${git_upstream} +Let's first clone git repo and ensure that some files in container will be owned by jekyll: -for i in .jekyll-cache vendor vendor/bundle _site ; do - podman unshare mkdir -p ${git_directory}/centos.org/${i} - podman unshare chown -R 1000:1000 ${git_directory}/centos.org/${i} -done -podman unshare chown -R 1000:1000 ${git_directory}/centos.org/Gemfile.lock -popd -``` + test -d ${git_directory} || mkdir -p ${git_directory} + pushd ${git_directory} + test -d centos.org || git clone ${git_upstream} -Let's now for the first time launch jekyll : + for i in .jekyll-cache vendor vendor/bundle _site ; do + podman unshare mkdir -p ${git_directory}/centos.org/${i} + podman unshare chown -R 1000:1000 ${git_directory}/centos.org/${i} + done + podman unshare chown -R 1000:1000 ${git_directory}/centos.org/Gemfile.lock + popd -``` -podman images |grep -q jekyll || podman run --volume="${git_directory}/centos.org:/srv/jekyll:z" --volume="${git_directory}/centos.org/vendor/bundle:/usr/local/bundle:z" --rm -it jekyll/jekyll bundle update -``` +Let's now for the first time launch jekyll: -If that works, you'll have everything you need. You can then render/build the website (under _site directory) like this : + podman images |grep -q jekyll || podman run --volume="${git_directory}/centos.org:/srv/jekyll:z" --volume="${git_directory}/centos.org/vendor/bundle:/usr/local/bundle:z" --rm -it jekyll/jekyll bundle update -``` -podman run --volume="${git_directory}/centos.org:/srv/jekyll:z" \ - --volume="${git_directory}/centos.org/vendor/bundle:/usr/local/bundle:z" \ - --rm -it jekyll/jekyll jekyll build -``` +If that works, you'll have everything you need. You can then render/build the +website (under _site directory) like this: -The better way to work on changes is to have jekylly to automatically "watch" for local changes, and rebuild automatically on the fly when it detects that files were added/modified. To do this, and then to be able to browse "live" onhttp://localhost:4000 , launch Jekyll like this : + podman run --volume="${git_directory}/centos.org:/srv/jekyll:z" \ + --volume="${git_directory}/centos.org/vendor/bundle:/usr/local/bundle:z" \ + --rm -it jekyll/jekyll jekyll build -``` -podman run --volume="${git_directory}/centos.org:/srv/jekyll:z" \ - --volume="${git_directory}/centos.org/vendor/bundle:/usr/local/bundle:z" \ - -p 4000:4000/tcp \ - --rm -it jekyll/jekyll jekyll serve -``` +## Running + +### Development + +The better way to work on local changes is to have jekyll to automatically +"watch" for local changes, and rebuild automatically on the fly when it detects +that files were added/modified. To do this, and then to be able to browse +"live" onhttp://localhost:4000, launch Jekyll like this: + + podman run --volume="${git_directory}/centos.org:/srv/jekyll:z" \ + --volume="${git_directory}/centos.org/vendor/bundle:/usr/local/bundle:z" \ + -p 4000:4000/tcp \ + --rm -it jekyll/jekyll jekyll serve + +### Production + +The `jekyll serve` command fits well on development environments, however when +you want to use a more robust web server (e.g., Apache, Nginx) in production +environments the `jekyll serve` command may be not appropriate. Instead, you +may use the `jekyll build --watch` command inside a container and control it +using systemd. In this configuration the web server should be configured to +expose the `${git_directory}/centos.org/_site/` directory as document root, the +place where jekyll build command renders the final files. + +1. Create a detached container running `jekyll build --watch` command: + + podman run -d --volume="${git_directory}/centos.org:/srv/jekyll:z" \ + --volume="${git_directory}/centos.org/vendor/bundle:/usr/local/bundle:z" \ + -it --name www.centos.org docker.io/jekyll/jekyll:latest jekyll build --watch + +2. Use podman-generate-systemd(1) command to create the systemd service unit + under the `~/.config/systemd/user/` directory. If this directory doesn't + exist, create it. + + cd ~/.config/systemd/user/ + podman generate systemd --files --name www.centos.org + +3. Stop the container previously created. Don't remove it. It will be + controlled by systemd. + + podman stop www.centos.org + +4. Enable and start the container using systemctl command. + + systemctl --user enable container-www.centos.org.service + systemctl --user start container-www.centos.org.service + +5. To start the service at system start and persist over user logouts, enter + (as root user): + + loginctl enable-linger + +Reference: + +* https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/building_running_and_managing_containers/porting-containers-to-systemd-using-podman_building-running-and-managing-containers ### Opening a PR (Merge request) -Once you're satisfied with local changes, proceed as usual : - - * `git commit` and `git push` to origin (your fork) - * open PR on git.centos.org -### Reviewing a PR (for admins) -When someone will open a PR, there is a way to pull locally the proposed changed and render locally. -We can apply the method above with "jekyll serve" but we can pull locally. -On each PR, there is a link at bottom named "Pull this pull-request locally" with a link to instructions. -If you proceed, that will create a new temporary branch named pr, so you can then `git checkout pr` , render website automatically and see if that looks ok. -If it is, you can go back to git.centos.org, and then either comment (if you need some changes) or just `merge` it. -Merging it in main branch will automatically means that website will be rebuild and pushed in the next minute[s] to www.centos.org nodes. +Once you're satisfied with local changes, proceed as usual: + * `git commit` and `git push` to origin (your fork) + * open PR on git.centos.org +### Reviewing a PR (for admins) +When someone will open a PR, there is a way to pull locally the proposed +changed and render locally. We can apply the method above with "jekyll serve" +but we can pull locally. On each PR, there is a link at bottom named "Pull +this pull-request locally" with a link to instructions. If you proceed, that +will create a new temporary branch named pr, so you can then `git +checkout pr`, render website automatically and see if that looks ok. +If it is, you can go back to git.centos.org, and then either comment (if you +need some changes) or just `merge` it. Merging it in main branch will +automatically means that website will be rebuilt and pushed in the next +minute[s] to www.centos.org nodes.