mobrien / centos / centos.org

Forked from centos/centos.org 3 years ago
Clone

Blame README.md

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