How to use the command 'agate' (with examples)

Agate is a simple server implementation for the Gemini protocol, which is a lightweight internet protocol designed to be simpler and more privacy-respecting than HTTP. Agate serves documents over the Gemini protocol, which emphasizes minimalism and textual content similar to Gopher. It’s designed to be easy to set up and use, making it ideal for those looking to host small, private, or experimental websites. Below, we will explore the different ways to use the agate command through practical examples.

Use case 1: Run and generate a private key and certificate

Code:

agate --content path/to/content/ --addr [::]:1965 --addr 0.0.0.0:1965 --hostname example.com --lang en-US

Motivation:

This use case is crucial for users looking to set up their Gemini server for the first time. By running this command, a private key and a self-signed certificate are generated automatically. These are essential for serving content securely over the Gemini protocol, as encryption and authentication are important facets of its design. Generating and configuring these elements makes the server ready to serve requests over the Gemini network immediately.

Explanation:

• --content path/to/content/: This argument specifies the directory where your Gemini content is stored. It’s essential to provide a path to ensure the server knows what content to serve to visitors.

• --addr [::]:1965: This argument binds the server to IPv6 address, ensuring compatibility with both IPv4 and IPv6 networks. The port number 1965 is the standard for Gemini servers, similar to how 80 is standard for HTTP.

• --addr 0.0.0.0:1965: This is the IPv4 counterpart of the above argument. It ensures that the server is accessible over IPv4 as well.

• --hostname example.com: This is the hostname of your server, by which it will be reachable over the Gemini network. It’s necessary for correctly signing the certificate.

• --lang en-US: This specifies the default language of the content being served, helping clients understand and potentially translate content.

Example Output:

Upon executing the command, agate outputs information about where the key and certificate have been generated, binds to the specified addresses, and begins to serve the content from the specified directory. You would see a confirmation like this:

Generating new private key and self-signed certificate for example.com
Serving Gemini protocol on [::]:1965 and 0.0.0.0:1965

Use case 2: Run server

Code:

agate path/to/file

Motivation:

This simple command is meant for users who wish to quickly serve a specific Gemini file rather than a directory. This could be useful for debugging, testing specific content, or serving a singular, standalone document without the need of a broader content directory structure.

Explanation:

• path/to/file: This argument is the path to a single file that you want to serve over Gemini. By specifying a file path directly, you focus the server’s scope, making it quick and efficient for serving or testing single documents.

Example Output:

The output for this command confirms the file is being served and indicates the server address. For instance:

Serving content from path/to/file at gemini://localhost:1965

Use case 3: Display help

Code:

agate -h

Motivation:

Using this command is valuable for any user who needs to understand the various options and flags available for configuration in agate. Displaying the help dialog is often a starting point for beginners to get acquainted with different functionalities or for experienced users to quickly recall command syntaxes.

Explanation:

• -h: This flag triggers the display of help information. It’s a standard in many command-line applications to provide users with a summary of command options and usage guidelines without executing further actions.

Example Output:

The output provides a comprehensive list of command options and their descriptions:

Usage: agate [options]
Options:
  --content <path>        Serve files from specified directory
  --addr <address>        Bind to specified address (default :1965)
  [other options...]

Conclusion:

Agate proves to be a streamlined and versatile tool for hosting Gemini servers. Whether you’re initializing a full-fledged server with encryption, testing standalone content, or just exploring the command options, agate offers simplicity and flexibility. The examples above provide a basis from which users can grow their Gemini-hosting capabilities in alignment with their particular needs.