Apache Guacamole is a clientless remote desktop gateway, and its website is crafted with care using Jekyll, HTML, and Markdown. In this guide, we’ll walk you through the steps to build and serve the Apache Guacamole website effectively. Whether you’re developing locally or using Docker, this article has you covered.

Table of Contents

• Repository Structure
• Build Prerequisites
• Testing Changes Locally
• Build and Serve Using Docker
• Publishing Changes
• Troubleshooting

Repository Structure

The Apache Guacamole website repository contains various important files, including:

• _config.yml – Contains configuration information for building with Jekyll.
• build.sh – A script for building the website.
• doc/ – Contains documentation for each release of Apache Guacamole.
• Dockerfile – Used for creating a Docker image to serve the website.
• styles/ – Contains the CSS files for styling the website.
• _includes/ – Common HTML fragments used in the site’s templates.
• _layouts/ – Contains various templates for different content types.

Build Prerequisites

Before you start building the website, ensure the following tools are installed:

• Jekyll – Refer to Jekyll’s own installation instructions to set this up.
• A POSIX-compliant implementation of sh to run the build.sh.
• git for cloning the repository and publishing changes.
• mktemp is required by the build script during staging.

Testing Changes Locally

To see your changes come to life, you can test your modifications locally by running:

./build.sh

Alternatively, to serve content at a specific port, execute:

./build.sh PORT

For example, to use port 8080:

./build.sh 8080

After making your tests, press Ctrl + C to stop the server.

Build and Serve Using Docker

For those preferring Docker, you can set up the website without installing Jekyll directly. Follow these steps:

1. Build the Docker image:

docker build . -t some-website

2. Run the Docker container on a specific port:

docker run -e PORT=8080 -p 8080:8080 -it --rm some-website

Press Ctrl + C to stop the Docker container once you’re done.

Publishing Changes

Publishing requires you to update the special asf-site branch. To do this:

1. Make and test your changes locally.
2. Use ./build.sh stage to prepare your updates for the repository.
3. Switch to the asf-site branch and commit your changes.

git push origin asf-site

Make sure the staged content appears as expected before committing.

Troubleshooting

If you encounter issues during building or serving, here are some troubleshooting steps:

• Verify that Jekyll is correctly installed and accessible.
• Ensure all dependencies (like git, sh, and mktemp) are installed.
• Check for typos in command lines or configuration files.
• Review the console output for error messages that may indicate missing files or configurations.

For more insights, updates, or to collaborate on AI development projects, stay connected with fxis.ai.

At fxis.ai, we believe that such advancements are crucial for the future of AI, as they enable more comprehensive and effective solutions. Our team is continually exploring new methodologies to push the envelope in artificial intelligence, ensuring that our clients benefit from the latest technological innovations.