This repository contains the source for the website of Apache Guacamole, a clientless remote desktop gateway.
The website itself is completely static, being automatically generated by Jekyll prior to deployment. The content of the website is written in a mixture of HTML and Markdown, with dynamic portions written using liquid templating. Templated content is interpreted only a build time, with the final result being completely static.
To facilitate ease of development and testing, this repository also contains a
build script, build.sh, the usage of which is documented below.
In addition to the LICENSE and NOTICE files required of any proper Apache-
licensed project, the repository contains the following critical files:
| Filename | Description |
|---|---|
_config.yml |
Configuration information controlling the Jekyll build. This is a standard Jekyll file. See: Jekyll directory structure |
add-tracking.pl |
Utility script which edits specified HTML files in-place, adding the project's Google Analytics tracking code at the end of the <body> (requires Perl). |
build.sh |
The website build script (usage documented below). |
doc/ |
Per-release documentation for Apache Guacamole. This directory contains one subdirectory per release, where each subdirectory contains the overall manual (.../gug/) API documentation for each part of the Guacamole core (.../libguac/, .../guacamole-common/, etc.). Files in this directory are not interpreted by Jekyll, as there are far too many files for this to be reasonable. They are instead copied into place by the build.sh script. |
Dockerfile |
A docker file that can be used to build and serve the website. |
images/ |
Images which are referenced within the website HTML and CSS. |
pub/ |
Miscellaneous public files, such as test scripts. The test scripts in this directory have historically been shared to users to help with debugging. |
styles/ |
All CSS files referenced by the website HTML. |
_companies/ |
Documents which contain metadata describing third-party companies that provide support for Apache Guacamole. The content of these documents is rendered as the description for that company on the support page. |
_includes/ |
Common HTML fragments used by Jekyll and referenced in other templates, such as the website header and footer. These must be HTML only. This is a standard Jekyll directory. See: Jekyll directory structure |
_layouts/ |
Templates describing the structure of different types of content. This is a standard Jekyll directory. See: Jekyll directory structure |
_links/ |
Documents which contain metadata describing the links which should appear in the site navigation menu. The documents here are completely empty except for the metadata. |
_releases |
Release notes for Guacamole releases, including metadata describing the files and documentation associated with those releases. |
The build depends entirely on Jekyll, thus this must be installed first. If you do not yet have Jekyll installed, please see Jekyll's own installation instructions to get started.
Beyond Jekyll, you will also need:
- A POSIX-compliant implementation of
sh(to runbuild.sh) - git (to clone this repository and to publish changes)
mktemp(used bybuild.shwhen staging changes prior to publishing)
The build.sh script will check whether the required programs are installed,
and will fail early with an appropriate message if a required program cannot be
found.
The build script handles three primary variations of common build tasks:
- The build itself, when invoked as
./build.sh. This invokes Jekyll and recursively copies thedoc/(part of the website source) and_site/(generated by Jekyll during the build) to thecontent/directory. - Serving a local copy of the website, when invoked as
./build.sh PORT. - Staging local changes for commit to the special "asf-site" branch, when invoked as
./build.sh stage. Once changes are committed and pushed to "asf-site", the public website will be updated by the ASF's gitpubsub.
To test your changes to the website, you can either invoke ./build.sh to build a static copy of the site to the content/ subdirectory, or invoke ./build.sh PORT (where PORT a TCP port number) to both build the static copy of the site and run Ruby's web server to serve content/ locally at the given port:
$ ./build.sh 8080
Configuration file: /home/mjumper/apache-guacamole/guacamole-website/_config.yml
Source: /home/mjumper/apache-guacamole/guacamole-website
Destination: /home/mjumper/apache-guacamole/guacamole-website/_site
Incremental build: disabled. Enable with --incremental
Generating...
done in 0.563 seconds.
Auto-regeneration: disabled. Use --watch to enable.
Copying "doc/" and built site to "content/" ...
Done. Full site is now within the "content/" directory.
[2016-04-26 12:35:36] INFO WEBrick 1.3.1
[2016-04-26 12:35:36] INFO ruby 2.1.7 (2015-08-18) [x86_64-linux]
[2016-04-26 12:35:36] INFO WEBrick::HTTPServer#start: pid=18927 port=8080
When done testing your local changes, press Ctrl + C to stop the
web server and return to the shell.
Alternatively, as opposed to installing Jekyll locally, the website can be built and served locally using the provided Dockerfile. To build and serve the website locally, simply build a Docker container containing the current website and run the container, as below.
- Build a new docker image:
docker build . -tag some-website. - Run the docker image at a configured port:
docker run -e PORT=8080 -p 8080:8080 -it --rm some-website
The website will be served just as when build.sh is invoked directly. Press Ctrl + C to stop the docker container.
Changes to the website are published using Apache's
gitpubsub
which relies on a special branch called "asf-site" containing all website
content within a directory called content/.
In the Apache Guacamole website repository, the "asf-site" branch is an "orphan"
branch. The branch has no commits in common with the "master" branch and
consists solely of the content/ subdirectory. Updating the website thus
involves:
- Making and testing your changes locally
- Replacing the entire contents of the
content/directory within "asf-site" with the newly-generatedcontent/directory.
The build.sh script can take care of all this for you when invoked as
./build.sh stage:
$ ./build.sh stage
Configuration file: /home/mjumper/apache-guacamole/guacamole-website/_config.yml
Source: /home/mjumper/apache-guacamole/guacamole-website
Destination: /home/mjumper/apache-guacamole/guacamole-website/_site
Incremental build: disabled. Enable with --incremental
Generating...
done in 0.568 seconds.
Auto-regeneration: disabled. Use --watch to enable.
Copying "doc/" and built site to "content/" ...
Done. Full site is now within the "content/" directory.
Switched to branch 'asf-site'
Removing README.md
Removing _site/
Content staged for commit. Use git to commit the results when ready.
NOTE: The build.sh script will no longer exist. To serve the staged
contents, run:
ruby -run -e httpd content/ -p PORT
where PORT is the port number where the HTTP server should listen.
$
At this point, you will be on the "asf-site" branch and the current directory
will contain only the content/ subdirectory:
$ ls
content
$
Keep in mind that the new content is only staged for commit. It has not yet
been committed. Once you have verified that the staged content is as expected,
commit your changes (along with a useful commit message describing the changes
at a high level) using git commit and publish the update using
git push origin.
If you wish to unstage your changes, use git reset --hard HEAD to return to
the original state of "asf-site", wiping out any local modifications made by
build.sh. You can then return to whichever branch you were working on with
git checkout.