Repository files navigation

This is the source code for theDebezium website. This is based ontemplates created by the Red Hat upstream community usingJekyll.

For publishing the Debezium reference documentation, theAntora tool is used,which produces the documentation based onAsciiDoc files in different branches of the Debezium main code repository.The rendered HTML pages are added as-is to the website generated with Jekyll.Please seeANTORA.md to learn more.

Contents of this repository are available as open source software underApache License Version 2.0.

We useDocker to build the site. Be sure you have a recent version of theDocker Engine orDocker Machine.

Use Git to clone the Debezium website Git repository and change into that directory:

$ git clone https://github.com/debezium/debezium.github.io.git$ cd debezium.github.io

If you plan to submit changes, fork theGit repository on GitHub and then add your fork as a remote:

$ git remote rename origin upstream$ git remote add origin https://github.com/<you>/debezium.github.io.git

Then check out thedevelop branch and get the latest. If you're going to make changes, create a topic branch and make the changes there.

There are two recommended ways for previewing the website locally, either via the container environment that's also used on CI for publishing the website, or via a Jekyll install on your machine.The latter is a bit quicker, but requires Ruby/Jekyll to be set up correctly, whereas you get this "for free" via the container image.

In a new terminal initialized with the Docker host environment, start a Docker container that has the build environment for our website:

$ docker run --privileged -it --rm -p 4000:4000 -e LC_ALL=C.UTF-8 -e LANG=C.UTF-8 -v $(pwd):/site --name website-builder quay.io/debezium/website-builder bash

This command tells Docker to start a container using thequay.io/debezium/website-builder image (downloading it if necessary) with an interactive terminal (via-it flag) to the container so that you will see the output of the process running in the container. The--rm flag will remove the container when it stops, while the-p 4000 flag maps the container's 4000 port to the same port on the Docker host (which is the local machine on Linux or the virtual machine if running Boot2Docker or Docker Machine on OS X and Windows). The-v $(pwd):/site option mounts your current working directory (where the website's code is located) into the/site directory within the container.

Next, in the shell in the container, run the following commands to update and then (re)install all of the Ruby libraries required by the website:

jekyll@49d06009e1fa:/site$ bundle updatejekyll@49d06009e1fa:/site$ bundle install

This should only need to be performed once. After the libraries are installed, we can then build the site from the code so you can preview it in a browser:

jekyll@49d06009e1fa:/site$ rake clean preview

The site generation process is integrated with Antora. Antora generates the version-specific documentation from the main Debezium GitHub repository, and is invoked prior to Jekyll for inclusion in the website. The default mode using the above commands will fetch the Debezium codebase from GitHub. If you wish to generate the Debezium documentation using your local Debezium git repository, see the next section. For more specifics on the Antora build, please seeANTORA.md

The default process (outlined in the previous section) will generate the Debezium version-specific documentation from the Debezium repository on GitHub. However you may want to view or edit the documentation found in your local Debezium git repository. In this case, the steps are slightly different.

First, you must have a local clone of theDebezium repository.

Then start the Docker container:

$ docker run --privileged -it --rm -p 4000:4000 -e LC_ALL=C.UTF-8 -e LANG=C.UTF-8 -v $(pwd):/site -v ~/<PATH_TO_REPOS>/debezium:/debezium --name website-builder quay.io/debezium/website-builder bash

Note the addition of the volume mapping-v ~/<PATH_TO_REPO_DIR>/debezium:/debezium - ( replace <PATH_TO_REPO_DIR> with the actual location on your system ).

Next, in the shell in the container, run the following commands to update and then (re)install all of the Ruby libraries required by the website:

jekyll@49d06009e1fa:/site$ bundle updatejekyll@49d06009e1fa:/site$ bundle install

This should only need to be performed once. After the libraries are installed, we can then build the site from the code so you can preview it in a browser:

jekyll@49d06009e1fa:/site$ rake clean author preview

The additionalauthor arg above sets the environment to useplaybook_author.yml instead ofplaybook.yml for Antora, which then builds the Debezium docs from the local repo. For more specifics on the Antora build, please seeANTORA.md

Run the following steps once to set up your local Jekyll installation.

• InstallRVM, the Ruby version manager(seehere why to use RVMand Bundler).

• Install Ruby:

    rvm install ruby-2.7.2

• Create agemset for all the dependencies to be installed:

    rvm ruby-2.7.2 do rvm gemset create debezium.io

• Create a file named.rvmrc in this directory (debezium.github.io) with the following contents:

    rvm use 2.7.2@debezium.io

• Change out of this directory and back in again, it should display a message like this:

    cd .. && cd debezium.github.io  Using /Users/gunnar/.rvm/gems/ruby-2.7.2 with gemset debezium.io

• Install all dependencies

    bundle update  bundle install

With this set-up in place, you can preview the website by running Jekyll like so:

bundle exec jekyll serve --livereload --incremental

Point your browser tohttp://localhost:4000 to view the site. You may notice some delay during development, since the site is generated somewhat lazily.

Use any development tools on your local machine to edit the source files for the site.Jekyll will detect the changes and may regenerate the corresponding static file(s).

If you have to change the Gemfile to use different libraries, you will need to let the container download the new versions. The simplest way to do this is to stop the container (using CTRL-C), userm -rf bundler to remove the directory where the gem files are stored, and then restart the container. This ensures that you're always using the exact files that are specified in the Gemfile.lock file.

Use Git on your local machine to commit the changes to the site's codebase to your topic branch, and then create a pull request.

As soon as you passes the pull request a GitHub action generates the link for preview the change in surge.sh. When a pull request is closed the surge preview instance will be torn down.

Review the pull request and merge onto thedevelop branch. TheGitHub Actions will then build thedevelop branch and, if successful, store the generated site in thegh-pages branch and publish to GitHub Pages.