Skip to content

GEODE-7303: Simplify native client UG builds #538

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
davebarnes97 merged 1 commit into from
Oct 18, 2019
Merged

GEODE-7303: Simplify native client UG builds #538

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 5 additions & 98 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,110 +2,17 @@

This document contains instructions for building and viewing the Apache Geode Native Client User Guides.

- [About](#about)
- [Bookbinder Usage](#bookbinder-usage)
- [Docker Setup](#docker-setup)
- [Building the Documentation](#building-the-documentation)

<a name="about"></a>
## About

The Geode-Native repository provides the full source for the Apache Geode Native Client User Guides in markdown format (see _geode-project-dir_/geode-docs/CONTRIBUTE.md for more information on how to use markdown in this context). Users can build the markdown into an HTML user guide using [Bookbinder](https://github.com/pivotal-cf/bookbinder) and the instructions below.

The User Guide can be produced in two versions: one for the .NET native client, the other for the C++ native client. You specify which version to build by copying two language-specific configuration files, each to its generically-named counterpart, then running the Bookbinder build.

For example, to build the .NET version of the Native Client User Guide, first copy the DOTNET configuration files to their generically-named counterparts:

```
cd geode-native-book
cp config.yml.DOTNET config.yml
cp redirects.rb.DOTNET redirects.rb
```
Then run Bookbinder to create the guide.

Similarly, to generate the C++ Native Client User Guide, first copy the CPP configuration files:

```
cd geode-native-book
cp config.yml.CPP config.yml
cp redirects.rb.CPP redirects.rb
```
Then run Bookbinder to create the guide.

Bookbinder is a Ruby gem that binds a unified documentation web application from markdown, html, and/or DITA source material. The source material for bookbinder must be stored either in local directories or in GitHub repositories. Bookbinder runs [Middleman](http://middlemanapp.com/) to produce a Rackup app that can be deployed locally or as a web application.

<a name="bookbinder-usage"></a>
## Bookbinder Usage

Bookbinder is meant to be used from within a project called a **book**. The book includes a configuration file that describes which documentation repositories to use as source materials. Bookbinder provides a set of scripts to aggregate those repositories and publish them to various locations.

For Geode Native Client, a preconfigured **book** is provided in the directory _geode-native-project-dir_/docs/geode-native-book. The book gathers content from the language-specific directory _geode-native-project-dir_/docs/geode-native-docs-dotnet or geode-native-docs-cpp. You can use this configuration to build an HTML version of the Apache Geode Native Client User Guides on your local system.

<a name="docker-setup"></a>
## Docker Setup

For ease of use, a Docker image is provided that contains a self-consistent Bookbinder environment. [Install Docker](https://docs.docker.com/install/) if you have not already done so.

<a name="building-the-documentation"></a>
## Building the Documentation

1. Navigate to the directory that contains the Dockerfile and run the `docker build` command to create the Bookbinder-enabled Docker image:

```bash
$ cd geode-native/docs/docker
$ docker build -t geode-native-userman .
```

1. Run the Docker image in interactive mode with a command similar to the following:

```bash
$ docker run -it -p 9292:9292 -p 1234:1234 -v PATH-TO-GEODE-NATIVE/docs:/docs geode-native-userman
```

where `PATH-TO-GEODE-NATIVE` is the fully-qualified path to the geode-native repo. This brings up the interactive Docker container, with `/` as your current working directory.

1. To build the documentation, `cd` to the book directory:

```bash
$ cd docs/geode-native-book
```

1. Run `bundle install` to install the dependencies required to build the user guide.

```bash
$ bundle install
```

1. Copy the language-specific configuration files to their generically-named counterparts. For the .NET book, copy the DOTNET configuration files to their generically-named conterparts:

```
cd geode-native-book
cp config.yml.DOTNET config.yml
cp redirects.rb.DOTNET redirects.rb
```

Similarly, to generate the C++ Native Client User Guide, first copy the CPP configuration files:

```
cd geode-native-book
cp config.yml.CPP config.yml
cp redirects.rb.CPP redirects.rb
```

1. Invoke bookbinder to build the user guide. Bookbinder converts the markdown source into HTML, which it puts in the `final_app` directory:

```bash
$ bundle exec bookbinder bind local
```

1. To start a local website of the Apache Geode Native Client User Guide, navigate to the `final_app` directory and run `rackup`:
The User Guide can be produced in two versions: one for the .NET native client, the other for the C++ native client.

```bash
$ cd final_app
$ rackup
```
## Automatic build

Note: You may be prompted to run `bundle install` to supply any missing components. Do that, then re-try the `rackup` command.
Documentation can be built and previewed using the utility scripts at [docs/docker](https://github.com/apache/geode-native/tree/develop/docs/docker). These scripts use Docker, removing the requirement of installing Ruby and Bookbinder. They are based on the instructions described in [docs/manual-build](https://github.com/apache/geode-native/tree/develop/manual-build).

You can now view the local documentation in a browser at <http://localhost:9292>.
## Manual build

Documentation can be built in a less-automated way, as described at [docs/manual-build](https://github.com/apache/geode-native/tree/develop/manual-build).
26 changes: 7 additions & 19 deletions docs/docker/Dockerfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,24 +14,12 @@
# See the License for the specific language governing permissions and
# limitations under the License.

FROM ubuntu:latest
FROM ruby:2.3.1

RUN apt-get update
RUN apt-get install -y curl git gnupg2
RUN gpg2 --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB || \
gpg2 --keyserver hkp://pgp.mit.edu --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB || \
gpg2 --keyserver hkp://ha.pool.sks-keyservers.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
LABEL Vendor="Apache Geode"
LABEL version=unstable
LABEL maintainer=dev@geode.apache.org

RUN \curl -sSL https://get.rvm.io | bash
RUN /bin/bash -l -c "rvm requirements"
RUN /bin/bash -l -c "rvm install 2.3.0"
RUN /bin/bash -l -c "gem install bundler --no-document -v '=1.16.1'"

RUN /bin/bash -l -c "cp /etc/hosts ~/hosts.new"
RUN /bin/bash -l -c 'sed -i -E "s/(::1\s)localhost/\1/g" ~/hosts.new'

RUN echo "alias rackup='rackup -o 0.0.0'" >> /etc/profile

EXPOSE 9292

ENTRYPOINT ["/bin/sh", "-c" , "cat ~/hosts.new > /etc/hosts && . /etc/profile && alias rackup='rackup -o 0.0.0.0' && /bin/bash -l" ]
ADD Gemfile Gemfile
ADD Gemfile.lock Gemfile.lock
RUN bundle install
34 changes: 34 additions & 0 deletions docs/docker/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Automatic generation of Apache Geode Native Client User Guides
This document contains instructions for building and viewing the Apache Geode Native Client User Guides for C++ and .NET languages.


## Building the User Guides
The build-docs.sh script invokes Bookbinder to transform the markdown files to HTML using Docker, which has been provisioned with Bookbinder and Ruby. To build the guide, run the script from a shell prompt:

- For C++ user guide:
```
$ ./build-docs.sh cpp
```

- For .NET user guide:
```
$ ./build-docs.sh dotnet
```

## Viewing the User Guides
After the HTML files are generated, view-docs.sh can be used to start a webserver and review the documentation.

- For C++ user guide:
```
$ ./view-docs.sh cpp
```
In a browser, navigate to `http://localhost:9191` to view the user guide.

- For .NET user guide:
```
$ ./view-docs.sh dotnet
```
In a browser, navigate to `http://localhost:9292` to view the user guide.


The other files in this folder (`build-image-common.sh` and `Dockerfile`) are utilities used by `build-docs.sh` and `view-docs.sh`.
69 changes: 69 additions & 0 deletions docs/docker/build-docs.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
#!/bin/bash

# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

set -u

if [ "$#" -ne 1 ]; then
echo "ERROR: Illegal number of parameters"
echo ""
echo "Usage: `basename $0` [ cpp | dotnet ]"
exit 1
fi
LANG=$1
if [ "${LANG}" != "cpp" ] && [ "${LANG}" != "dotnet" ]
then
echo "ERROR: Incorrect language specified."
echo ""
echo "Usage: `basename $0` [ cpp | dotnet ]"
exit 1
fi
SCRIPT_DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )

. $SCRIPT_DIR/build-image-common.sh

DOCS_DIR=${SCRIPT_DIR}/../
BOOK_DIR=${DOCS_DIR}/geode-native-book-${LANG}
LOG_FILE=${SCRIPT_DIR}/build-${LANG}-docs-output.txt

echo "Running Bookbinder inside Docker container to generate documentation..."
echo " Complete log can be found in ${LOG_FILE}"

docker run -i -t \
--rm=true \
-w "${BOOK_DIR}" \
-v "$PWD:${DOCS_DIR}" \
${IMAGE_NAME}-${USER_NAME} \
/bin/bash -c "bundle exec bookbinder bind local &> ${LOG_FILE}"

SUCCESS=$(grep "Bookbinder bound your book into" ${LOG_FILE})

if [[ "${SUCCESS}" == "" ]];then
echo "Something went wrong while generating documentation, check log."
else
echo ${SUCCESS}
fi

docker run -i -t \
--rm=true \
-w "${BOOK_DIR}" \
-v "$PWD:${DOCS_DIR}" \
${IMAGE_NAME}-${USER_NAME} \
/bin/bash -c "chown -R ${USER_ID}:${GROUP_ID} ${LOG_FILE} ${BOOK_DIR}/output ${BOOK_DIR}/final_app"


popd 1> /dev/null

63 changes: 63 additions & 0 deletions docs/docker/build-image-common.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
#!/bin/bash

# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

set -u

export DOCKER_ENV_VERSION="0.1"

SCRIPT_DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )

#Stupid OSX has a different mktemp command
TMP_DIR=`mktemp -d 2>/dev/null || mktemp -d -t 'geodedocs'`

function cleanup() {
rm -rf $TMP_DIR
}

trap cleanup EXIT

IMAGE_NAME="geode-native/docsbuild:${DOCKER_ENV_VERSION}"

pushd ${TMP_DIR} 1> /dev/null
cp ${SCRIPT_DIR}/Dockerfile .
cp ${SCRIPT_DIR}/../geode-native-book-${LANG}/Gemfile* .

echo "Building ${IMAGE_NAME} image..."
docker build -q -t ${IMAGE_NAME} .

popd 1> /dev/null

if [ "$(uname -s)" == "Linux" ]; then
USER_NAME=${SUDO_USER:=$USER}
USER_ID=$(id -u "${USER_NAME}")
GROUP_ID=$(id -g "${USER_NAME}")
else # boot2docker uid and gid
USER_NAME=$USER
USER_ID=1000
GROUP_ID=50
fi

echo "Building ${IMAGE_NAME}-${USER_NAME} image..."
docker build -q -t "${IMAGE_NAME}-${USER_NAME}" - <<UserSpecificDocker
FROM ${IMAGE_NAME}
RUN groupadd --non-unique -g ${GROUP_ID} ${USER_NAME}
RUN useradd -g ${GROUP_ID} -u ${USER_ID} -k /root -m ${USER_NAME}
ENV HOME /home/${USER_NAME}
UserSpecificDocker

# Go to root
pushd ${SCRIPT_DIR}/../ 1> /dev/null
59 changes: 59 additions & 0 deletions docs/docker/view-docs.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
#!/bin/bash

# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

set -e -u

if [ "$#" -ne 1 ]; then
echo "ERROR: Illegal number of parameters"
echo ""
echo "Usage: `basename $0` [ cpp | dotnet ]"
exit 1
fi

LANG=$1
if [ "${LANG}" != "cpp" ] && [ "${LANG}" != "dotnet" ]
then
echo "ERROR: Incorrect language specified."
echo ""
echo "Usage: `basename $0` [ cpp | dotnet ]"
exit 1
fi

PORT=9292
if [ "${LANG}" = "cpp" ]
then
PORT=9191
fi

SCRIPT_DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )

. $SCRIPT_DIR/build-image-common.sh

DOCS_DIR=${SCRIPT_DIR}/../
BOOK_DIR=${DOCS_DIR}/geode-native-book-${LANG}

echo "Starting up web server..."
docker run -i -t \
--rm=true \
-w "${BOOK_DIR}/final_app/" \
-v "$PWD:${DOCS_DIR}" \
-p 127.0.0.1:${PORT}:${PORT} \
${IMAGE_NAME}-${USER_NAME} \
/bin/bash -c "bundle install; rackup --host 0.0.0.0 -p ${PORT}"

popd 1> /dev/null

0 docs/geode-native-book/.gitignore → docs/geode-native-book-cpp/.gitignore
View file
Open in desktop
File renamed without changes.
0 docs/geode-native-book/Gemfile → docs/geode-native-book-cpp/Gemfile
View file
Open in desktop
File renamed without changes.
Loading