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
• 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

• 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 the redhataccess group in GitHub.
• You must be logged in to your account on GitHub.

Fork the repository so that you can create and work with branches independently of the redhataccess/pantheon repository.

1. In a web browser, navigate to https://github.com/redhataccess/pantheon
2. Click Fork.
3. Click your user space in GitHub.

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.

1. From a terminal, clone the repository:
   $ git clone git@github.com:/pantheon.git
2. Set up redhataccess/pantheon as the upstream:
   $ cd pantheon $ git remote add upstream git@github.com:redhataccess/pantheon.git

Whenever you work on a new issue, you must create a new working branch based on the latest version of the upstream master branch.

1. Ensure you are on master
   $ git checkout master
2. Ensure your fork is up to date
   $ git pull upstream master
3. Create a working branch based on the issue in JIRA:
   $ git checkout -b FCCEUD<ID#>

When your work is ready to be reviewed and merged, create a pull request.

1. Push your working branch to your fork:
   $ git push -u origin <branch_name>
2. From the repository page in GitHub, click New pull request.
3. Select your working branch from the compare list.
4. Add WIP to the title of the pull request.
5. Add the awaiting tech review label to the pull request.
6. In the pull request comment field, enter @redhataccess/pantheon-developers Please review for technical completeness and accuracy.
7. 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.

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.

When you have addressed all technical review and peer review comments, notify the developers to accept the pull request.

1. Remove WIP from the title of the pull request.
2. 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.

• Podman
• Buildah
• Java

(All commands from here on will be assumed to be run from the project's root directory)

./mvnw clean install

./mvnw test

The best way to run Pantheon is to install podman.

1. First, create a pod:

podman pod create --name pantheon -p 8080 -p 5005

This will create a pantheon pod with ports 8080 (for web access) and 5005 (for remote Java debugging) open.

1. Run a Mongo database container in the pod.

podman run --pod pantheon --name slingmongo -d mongo

1. Build the Pantheon Docker-formatted container image.

buildah bud --layers -f container/Dockerfile -t pantheon-app .

1. Run the Sling container pod in the pod.

podman run --pod pantheon -d -e SLING_OPTS='-Dsling.run.modes=oak_mongo -Doak.mongo.uri=mongodb://localhost:27017' --name pantheon-app pantheon-app

The Sling launchpad can be accessed at http://localhost:8080 and you can log in to it using the admin/admin username password combo.

This is useful when developing the application. To deploy the code live to a running application, all you have to do is

./mvnw clean package 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.

Head to http://localhost:8080/pantheon for the application's entry point.

For Sling's management UI, you can head to http://localhost:8080/starter/index.html

You can stop and start the pod as necessary with podman's pod command:

podman pod stop pantheon
podman pod start pantheon

Run the container without Mongo, but this will result in the data being destroyed with the container.

podman run --rm -p 8080:8080  YOURTAG

Open a terminal inside the container and debug

get the container process

podman ps

podman exec -it PROCESS bash

If making modifications that are entirely contained within the frontend, it is not necessary to use maven to rebuild and redeploy the package on every change.

These instructions provide an imperfect-but-workable shortcut that can accelerate development.

cd pantheon/frontend
yarn start

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

chromium-browser --disable-web-security --user-data-dir=/home/user/anywhere/chromeDev/ &

This works because there is code in app.tsx that preempts all fetch() calls and checks if the app is being served from localhost. If so, it modifies the request to point to localhost:8080 specifically, rather than localhost:9000 which is where webpack-dev-server serves the frontend code from.

It might be possible to improve this technique. Suggestions are welcome.

The source for the end user documentation is stored in /pantheon-bundle/src/main/resources/SLING-INF/content/docs/.