We are providing a step-by-step guidance to setup the Kafka site as your local apache server's homepage. This could be useful when you are contributing doc changes, and would like to have a easy way of displaying and debugging your modified website. The guidance itself is based on OSX, but should be easily adopted for other Linux / Unix OS as well.

1. Make Sure Apache HTTP Service is Already Installed

In OSX, Apache Http Service should be installed by default. To validate it, you can check if command "apachectl" exists or not:

sudo apachectl start

If Apache Web Service is not installed, follow this page to download and install it.

And then on your browser, see if

localhost

renders successfully or not. For example, by default it will load the page defined in

/Library/WebServer/Documents/index.html.en

And you should see "It Worked!" text.

2. Make Sure Kafka-Site Git Repo Exist

Make sure you have cloned your forked kafka-site git repo (e.g. https://github.com/guozhang/kafka-site) from the apache git repo (https://github.com/apache/kafka-site) in your local directory, and then add the apache git repot as an additional remote repo. For example, after these steps your local repo should look like:

guozhang @kafka-site: pwd

/Users/guozhang/Workspace/github/guozhangwang/kafka-site 


guozhang @kafka-site: git remote -v

apache	https://github.com/apache/kafka-site.git (fetch)

apache	https://github.com/apache/kafka-site.git (push)

origin	https://github.com/guozhangwang/kafka-site.git (fetch)

origin	https://github.com/guozhangwang/kafka-site.git (push)


guozhang @kafka-site: git checkout asf-site
 
guozhang @kafka-site: git branch

* asf-site

3. Modify the Apache Configuration

Now you need to find the Apache Http Service config file and start editing on it. The config file could be found as (depending on your OS type and version)

sudo vim /etc/apache2/httpd.conf

And make the following changes on this file:

Step 1. Uncomment the following two lines. This is to enable loading "mod_include" and "mod_rewrite" modules.

LoadModule include_module libexec/apache2/mod_include.so
...
LoadModule rewrite_module libexec/apache2/mod_rewrite.so

Step 2. Change "DocumentRoot" and "Directory" to your kafka-site repo directory; and change AllowOverride from "None" to "All".

#

# DocumentRoot: The directory out of which you will serve your

# documents. By default, all requests are taken from this directory, but

# symbolic links and aliases may be used to point to other locations.

#

DocumentRoot "/Users/guozhang/Workspace/github/guozhangwang/kafka-site"

<Directory "/Users/guozhang/Workspace/github/guozhangwang/kafka-site">

    #

    # Possible values for the Options directive are "None", "All",

    # or any combination of:

    #   Indexes Includes FollowSymLinks SymLinksifOwnerMatch ExecCGI MultiViews

    #

    # Note that "MultiViews" must be named *explicitly* --- "Options All"

    # doesn't give it to you.

    #

    # The Options directive is both complicated and important.  Please see

    # http://httpd.apache.org/docs/2.4/mod/core.html#options

    # for more information.

    #

    Options FollowSymLinks Multiviews

    MultiviewsMatch Any




    #

    # AllowOverride controls what directives may be placed in .htaccess files.

    # It can be "All", "None", or any combination of the keywords:

    #   AllowOverride FileInfo AuthConfig Limit

    #

    AllowOverride All




    #

    # Controls who can get stuff from this server.

    #

    Require all granted

</Directory>

4. Reload Apache HTTP Service Homepage

Now simply restarting the Http web service:

sudo apachectl restart

And refreshing on your browser should then show up the complete Kafka site.

localhost

From now on, when editing on your local kafka-site git repo, you can simply repeat the above step 4 and see how the changes will be displayed now. NOTE that your doc changes should most likely be in the kafka repo still, instead of the kafka-site repo, and in order to display these changes you should copy the modified docs to kafka-site repo into the matching release folders.

5. Shutdown Apache HTTP Service

If you want to shutdown the web server, simply type:

sudo apachectl stop