# guacamole-website **Repository Path**: Coding.com/guacamole-website ## Basic Information - **Project Name**: guacamole-website - **Description**: No description available - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: GUACAMOLE-1754-PR-build - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-03-10 - **Last Updated**: 2025-03-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README The Apache Guacamole website ============================ This repository contains the source for the website of [Apache Guacamole](http://guacamole.apache.org/), a clientless remote desktop gateway. The website itself is completely static, being automatically generated by [Jekyll](https://jekyllrb.com/) prior to deployment. The content of the website is written in a mixture of HTML and Markdown, with dynamic portions written using [liquid templating](https://jekyllrb.com/docs/templates/). 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](#repository-structure) * [Build prerequisites](#build-prerequisites) * [Testing changes locally](#testing-changes-locally) * [Publishing changes](#publishing-changes) 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](https://jekyllrb.com/docs/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 `` (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](https://jekyllrb.com/docs/structure/) | `_layouts/` | Templates describing the structure of different types of content. This is a standard Jekyll directory. See: [Jekyll directory structure](https://jekyllrb.com/docs/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](https://jekyllrb.com/docs/installation/) 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. Build and serve using docker ----------------------- 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. 1. Build a new docker image: `docker build . -tag some-website`. 2. 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. Publishing changes ------------------ Changes to the website are published using Apache's [gitpubsub](https://blogs.apache.org/infra/entry/git_based_websites_available) 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`.