Pantheon 2.x
Pantheon 2 is a modular documentation management and publication system based on asciidoc and built on top of Apache sling.
- Contributing to Pantheon
- Installing Pantheon
- Prerequisites
- Environment Variables
- Building the application
- Unit tests
- Running the application
- Live deploy of code
- Using the application
- Other use cases
- Developing the frontend code
- End user documentation
Contributing to Pantheon
Prerequisites
- You must have an account on GitHub. Signing up for a new GitHub account
- You must have registered SSH keys in your GitHub account. Adding a new SSH key to your GitHub account
- You must be a member of the
pantheon-doc-authors
team in theredhataccess
group in GitHub. - You must be logged in to your account on GitHub.
Forking the repository
Fork the repository so that you can create and work with branches independently of the redhataccess/pantheon
repository.
- In a web browser, navigate to https://github.com/redhataccess/pantheon
- Click Fork.
- Click your user space in GitHub.
Cloning the repository
After you have forked the repository, you must clone it to your local machine and add the original redhataccess/pantheon
repository as an upstream remote.
- From a terminal, clone the repository: $ git clone git@github.com:/pantheon.git
- Set up
redhataccess/pantheon
as the upstream: $ cd pantheon $ git remote add upstream git@github.com:redhataccess/pantheon.git
Creating a working branch
Whenever you work on a new issue, you must create a new working branch based on the latest version of the upstream master branch.
- Ensure you are on master $ git checkout master
- Ensure your fork is up to date $ git pull upstream master
- Create a working branch based on the issue in JIRA: $ git checkout -b FCCEUD<ID#>
Creating a pull request and completing review
When your work is ready to be reviewed and merged, create a pull request.
- Push your working branch to your fork: $ git push -u origin <branch_name>
- From the repository page in GitHub, click New pull request.
- Select your working branch from the compare list.
- Add
WIP
to the title of the pull request. - Add the awaiting tech review label to the pull request.
- In the pull request comment field, enter
@redhataccess/pantheon-developers Please review for technical completeness and accuracy
. - Click Create new pull request.
For code pull requests, one or more developers review the pull request. For documentation pull requests, the developers review the pull request for technical accuracy and documentation team members review the pull request for clarity, consistency, and compliance with necessary standards.
The review process
Both the technical review and peer review processes take place in pull requests in GitHub.
After creating and labeling a pull request as outlined above, the developers review the pull request and add comments regarding technical accuracy. Writers receive a notification that comments have been added via email, and when all comments have been addressed, the developers change the label from awaiting tech review to tech review passed.
When technical review is complete, writers click the Reviewers gear icon and select the name of a team member to request peer review. Writers receive a notification that comments have been added via email, and when all comments have been addressed, the reviewer clicks Review changes > Approve from the Files changed tab of the pull request to approve the changes and the pull request.
Merging a pull request
When you have addressed all technical review and peer review comments, notify the developers to accept the pull request.
- Remove
WIP
from the title of the pull request. - Click Request Review and enter
@redhataccess/pantheon-developers
.
The developers check that the Tech review passed label has been added to the pull request and peer pull request approval provided, then accept it.
Installing Pantheon
Prerequisites
- Podman
- Buildah
- Java
Environment Variables
Project Root Directory
The build script provided in scripts directory makes use of PANTHEON_CODEBASE environment variable. Set this variable in your .bashrc or .bash_profile script. PANTHEON_CODEBASE should point to the project's root directory.
Sling and MongoDB The scripts folder contains pantheon_karaf.exports file. It contains the values required for the pantheon karaf distribution. If you are running MongoDB on a different port then
- Make a copy of pantheon_karaf.exports file
- Place it in .pantheon directory under your home directory
- In
~/.pantheon/pantheon_karaf.exports
, update the MONGO_DB_URI variable
Building the application
(All commands from here on will be assumed to be run from the project's root directory)
sh scripts/deploy_local.sh
The deploy_local script will:
- Run maven build that creates the pantheon karaf distribution
- Extract the archive to $PANTHEON_CODEBASE/pantheon-karaf-dist/target. The distribution is being extracted to target, currently, because a fresh distribution is needed for changes in the pantheon-bundle codebase. In the future, that may change and accordingly script will also change.
- Start Karaf, and drop you into the karaf shell
Using the application
Head to http://localhost:8181/pantheon for the application's entry point.
For sling's management UI, you can head to http://localhost:8181/starter/index.html
Note: If you plan to use git import UI locally, please follow the instructions in README under tools/git2pantheon. Also you will need to set the credentials of the user that would be used by git2pantheon to push the repository. It can be done by using environment variables (for both podman based and non-podman based).
Other use cases...
Debug using Karaf shell
- To view logs: log:display
- To view exceptions: log:exception-display
- To list all bundles and view their status: bundle:list
- Find out why a bundle is in waiting state: diag [bundle-id]
Run the application using Podman
First, install podman.
Then, create a pod:
podman pod create --name pantheon-karaf -p 8181 -p 5005
This will create a pantheon-karaf
pod with ports 8181 (for web access) and 5005 (for
remote Java debugging) open.
Run a mongo database container in the pod.
podman run --pod pantheon-karaf --name slingmongo -d mongo
Build the pantheon image
buildah bud --layers -f container/Dockerfile -t pantheon-karaf-app .
Run the sling container in the pod.
podman run --pod pantheon-karaf -d -e MONGO_DB_REPLICA='mongodb://localhost:27017' -t --name pantheon-karaf-app pantheon-karaf-app
The Sling launchpad can be accessed at http://localhost:8181
and you can log in to
it using the admin/admin
username password combo.
Live deploy of code
This is useful when developing the application. To deploy the code live to a running application, all you have to do is
./mvnw clean install sling:install -pl pantheon-bundle
This will install the code in this project on the running Sling instance, where it can be previewed and modified.
Developing the frontend code
If making modifications that are entirely contained within the frontend, follow the instructions to build the application in this README, then
cd pantheon-bundle/frontend
# Install/update node deps
yarn
# Build the app
yarn build
# Run React dev server/process
yarn start
See the pantheon-bundle/frontend/README.md for more information on the development server
NOTE: It will likely be necessary to increase your inotify limit to ensure that yarn is able to detect changes in every project file. If you are running into issues with yarn not automatically detecting saved changes, run the following command (its effects are permenent):
echo fs.inotify.max_user_watches=65535 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p
It might be possible to improve this technique. Suggestions are welcome.
End user documentation
The source for the end user documentation is stored in /pantheon-bundle/src/main/resources/SLING-INF/content/docs/
.