# CentOS.org website

The CentOS.org website is using the following tools:

 * [jekyll](https://jekyllrb.com/) 4

 * [bootstrap](https://getbootstrap.com/) 4.

 * [podman](https://podman.io) (but should work with other know containers solutions too)

## Contributing to changes to this repo

### Needed 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

### 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)

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):

    export git_upstream="ssh://git@git.centos.org/forks/<ACO_LOGIN>/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:

    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 using jekyll-theme-centos container

image `v2.51.1-beta.49` version:

    install -d public

    podman run --rm \

      --name $@ \

      -v $PWD/src:/site \

      -v $PWD/public:/public \

      registry.gitlab.com/centos/artwork/centos-web/jekyll-theme-centos:v2.51.1-beta.49 \

      bundle exec jekyll build --config /site/_config.yml -s /site -d /public

### Versioning

The `jekyll-theme-centos` theme may introduce updates from time to time and

produce newer container images with them. To keep your site presentation

consistent, always use a fixed version when you run the jekyll build command.

## 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" on http://localhost:4000, launch Jekyll like this:

    install -d public

    podman run --rm -d \

      --name $@ \

      -v $PWD/src:/site \

      -v $PWD/public:/public \

      -p 0.0.0.0:4000:4000 \

      registry.gitlab.com/centos/artwork/centos-web/jekyll-theme-centos:v2.51.1-beta.49 \

      bundle exec jekyll serve -H 0.0.0.0 -p 4000 --config /site/_config.yml -s /site -d /public

### 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 <username>

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<number>, so you can then `git

checkout pr<number>`, 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.