Mirror of Apache Guacamole Website
JavaScript HTML CSS Other
Switch branches/tags
Nothing to show
Clone or download
Permalink
Failed to load latest commit information.
_companies GUACAMOLE-43: Add third party support company: Arcisphere LLC. May 31, 2016
_includes GUACAMOLE-471: Update copyright year in footer to 2018. Feb 7, 2018
_layouts GUACAMOLE-359: Add support for nested menus. Aug 4, 2017
_legacy-releases Switch to direct URL for legacy SourceForge downloads. Dec 20, 2016
_links Document frequently asked questions. Jan 23, 2018
_plugins Add cache-busting checksum to main.css link in head. Aug 5, 2017
_releases Mark 0.9.14 as released. Jan 18, 2018
_security Document vulnerabilities fixed prior to Guacamole's move to the ASF. Jan 8, 2018
doc Update top-level symbolic links to point to 0.9.14 documentation. Jan 18, 2018
icons Add icons/ directory from Apache HTTP Server (the icons are public do… Nov 21, 2016
images GUACAMOLE-43: Add third party support company: Arcisphere LLC. May 31, 2016
pub/tests Add doc/ and pub/ directories from old site. Remove Piwik tracking. Mar 24, 2016
scripts GUACAMOLE-359: Add support for nested menus. Aug 4, 2017
styles Document frequently asked questions. Jan 23, 2018
.gitignore Add content build script. Exclude output directory from git. Exclude … Apr 23, 2016
CONTRIBUTING GUACAMOLE-3: Add contribution guidelines (CONTRIBUTING). May 18, 2016
LICENSE Add LICENSE and NOTICE files. Apr 24, 2016
NOTICE GUACAMOLE-471: Update copyright year in NOTICE to 2018. Feb 7, 2018
README.md GUACAMOLE-436: Remove incubator- prefix from git repository names. Nov 29, 2017
_config.yml Add "Security Reports" page which lists vulnerabilities fixed in Apac… Jan 7, 2018
add-tracking.pl Add perl script for adding the Google Analytics tracking code to HTML. Nov 18, 2016
api-documentation.md GUACAMOLE-359: Use explicit menu links for all pages. Aug 4, 2017
build.sh The deploy branch is called asf-site, not asf-git. May 6, 2016
doap.rdf GUACAMOLE-436: Avoid redundant naming for DOAP file. Nov 17, 2017
faq.md GUACAMOLE-559: Update FAQ regarding new support for async clipboard API. May 4, 2018
guac-style.md GUACAMOLE-224: Update style guidelines to note that we don't accept "@… Feb 28, 2017
index.html List latest release on index. Dec 30, 2016
maturity-evaluation.md Evaluate and populate "Independence" section of maturity evaluation. Oct 22, 2017
open-source.md GUACAMOLE-436: Remove incubator- prefix from git repository names. Nov 29, 2017
pull-requests.md GUACAMOLE-436: Remove incubator- prefix from git repository names. Nov 29, 2017
release-procedure-part1.md GUACAMOLE-436: Remove incubator- prefix from git repository names. Nov 29, 2017
release-procedure-part2.md GUACAMOLE-436: Remove incubator- prefix from git repository names. Nov 29, 2017
release-procedure-part3.md GUACAMOLE-436: Remove incubator- prefix from git repository names. Nov 29, 2017
release-procedure-part4.md GUACAMOLE-436: Remove incubator- prefix from git repository names. Nov 29, 2017
releases.md GUACAMOLE-359: Use explicit menu links for all pages. Aug 4, 2017
security.md Point users to the new security@guacamole.apache.org list for reporti… Apr 13, 2018
support.md GUACAMOLE-436: Rename mailing list domains. Nov 17, 2017

README.md

The Apache Guacamole website

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.

Table of contents

Repository structure

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

Build prerequisites

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 run build.sh)
  • git (to clone this repository and to publish changes)
  • mktemp (used by build.sh when 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:

  1. The build itself, when invoked as ./build.sh. This invokes Jekyll and recursively copies the doc/ (part of the website source) and _site/ (generated by Jekyll during the build) to the content/ directory.
  2. Serving a local copy of the website, when invoked as ./build.sh PORT.
  3. 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.

Testing changes locally

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.

Publishing changes

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:

  1. Making and testing your changes locally
  2. Replacing the entire contents of the content/ directory within "asf-site" with the newly-generated content/ 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.