hermes

README

Hermes

Hermes is not an official HashiCorp project. The repository contains software which is under active development and is in the alpha stage. Please read the “Project Status” section for more information.

Hermes is an open source document management system created by HashiCorp to help scale the writing and document process. Read the release blog post here.

Hermes was created and is currently maintained by HashiCorp Labs, a small team in the Office of the CTO.

Please note: While this is not an official HashiCorp project, security is still very important to us! If you think that you've found a security issue, please contact us via email at security@hashicorp.com instead of filing a GitHub issue.

Usage

Setup

Google

1. Sign up for a Google Workspace account.

2. Create a Google Cloud project.

3. Enable the following APIs for Google Workspace APIs

   • Admin SDK API
   • Google Docs API
   • Google Drive API
   • Gmail API
   • People API
   • Also, to enable searching for users, the Google Workspace domain admin needs to enable external directory sharing. See more details: https://support.google.com/a/answer/6343701
     • Select Directory Setting >Sharing setting section > Contact sharing > Enable contact sharing

4. Configure the OAuth consent screen for the application in GCP project.

   • Enter a domain name in the “Authorized domains” section that Hermes may use. Example, mycompany.com
   • Add scopes:
     • https://www.googleapis.com/auth/drive.readonly

5. Create OAuth client ID credentials for a “web application”.

   • Add the following domains in the “Authorized JavaScript origins” section.

     • https://{HERMES_DOMAIN}
     • http://localhost:8000 (Note: this should be localhost when running locally)

   • Add the following URLs in the “Authorized redirect URIs” section.

     • https://{HERMES_DOMAIN}/torii/redirect.html
     • http://localhost:8000/torii/redirect.html (Note: this should be localhost when running locally)

   Please note the client ID as you may need it to be provided at application build time as the HERMES_WEB_GOOGLE_OAUTH2_CLIENT_ID environment variable.

6. Create OAuth client ID credentials for a “desktop application” for Hermes backend.

   • Download the OAuth credentials JSON file and save it to the root of this project repository.
   • Rename to credentials.json

Google Drive

We suggest using a shared drive for your organization.

• "Shortcuts" folder: this folder contains an organized hierarchy of folders and shortcuts to published files. You may want to share this with users if you need to provide a non-Hermes experience of navigating through Google Drive to find documents.

  • Structure: {doc_type}/{product}/{document}

• "Documents" folder: this folder contains all published documents in a flat structure. This folder should be shared with all of your users, but it is not ideal to view itself in Google Drive, given the flat structure. Instead, the "shortcuts folder" will provide a better viewing experience when navigating directly in Google Drive.

• "Drafts" folder: this folder contains all draft documents. It should be kept private and only accessible to the Hermes service user. The Hermes user will automatically share any draft documents with document owners and collaborators.

Example shared drive organization

• Shared Drives
  • Hermes
    • Documents (this is the "shortcuts" folder)
    • All Documents (this is the "documents" folder)
    • Drafts (this is the "drafts" folder)

Algolia (required)

1. Sign up for a free Algolia account.

The Application ID, Search API Key, and Write API Key in Algolia's API Keys settings are required for the Hermes server and the indexer. You will later add them to the config.hcl configuration file.

Similarly, you will use these values to set the HERMES_WEB_ALGOLIA_APP_ID and HERMES_WEB_ALGOLIA_SEARCH_API_KEY environment variables at build time.

Jira (optional)

Jira can be optionally configured to enable linking Hermes projects with Jira issues.

1. Create an API token for Jira.

2. Enable Jira using the jira block in the Hermes config file.

Development and Usage

Requirements

• Go 1.18
• Node.js 16
• Yarn ~3.3.0 (install with corepack)

Configuration File

Copy the example configuration file to the root of this repo and edit the file (it contains sensible defaults and comments to hopefully provide enough information to update necessary values).

cp configs/config.hcl ./
# Edit config.hcl...

Build the Project

make build

PostgreSQL

Hermes can be configured to point to any PostgreSQL database, but for running locally, there is tooling to start one in Docker using Docker Compose.

# Start PostgreSQL in Docker.
make docker/postgres/start

The database password can be configured via the Hermes config.hcl or the HERMES_SERVER_POSTGRES_PASSWORD environment variable.

Run the Server

./hermes server -config=config.hcl

Run the Indexer

./hermes indexer -config=config.hcl

NOTE: when not using a Google service account, this will automatically open a browser to authenticate the server to read and create documents, send emails, etc.

Running Hermes in Production

1. Create Service Account

• Create a new key (JSON type) for the service account and download it.
• Go to Delegating domain-wide authority to the service account and follow the instructions to enter the OAuth scopes.
• Add the following OAuth scopes (comma-delimited list): https://www.googleapis.com/auth/directory.readonly,https://www.googleapis.com/auth/documents,https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/gmail.send

1. Configure the service account in the auth block under the google_workspace config block.

More to come here...

Architecture

Server

The server process serves web content. Of note, there are API endpoints for an authenticated Algolia proxy (/1/ to allow usage of Algolia's client library), and redirect links (/l/) which provide human-readable links (i.e., /l/rfc/lab-123) to documents.

Indexer

The indexer is a process that is run alongside the server that continually polls for published document updates and reindexes their content in Algolia for search. Additionally, it will rewrite the document headers with Hermes metadata in case they are manually changed to incorrect values. While not strictly required, it is recommended to run the indexer so search index data and Google Docs stay up-to-date.

Frontend

The Ember.js web frontend is built and embedded into the Hermes binary, and served via the server process.

Project Status

This project is under active development and in the alpha stage. There may be breaking changes to the API, application configuration file, or other parts of the project. We recommend against installing builds from the main branch. We will make every attempt to document breaking changes and provide an upgrade path between releases of Hermes.

Feedback

If you think that you've found a security issue, please contact us via email at security@hashicorp.com instead of filing a GitHub issue.

Found a non-security-related bug or have a feature request or other feedback? Please open a GitHub issue.

Please note that it may take us up to a week to respond to GitHub issues as we continue to work on the project.

Contributing

In the short term, there are several large changes planned for the Hermes project. To make sure there aren’t any conflicts with the upcoming plans for the project, before submitting a PR please create a GitHub issue so we can validate the change you may want to propose.

As the project becomes more stable over the next several releases, we think it will become much easier to contribute.

Please note that it may take us up to a week to respond to PRs that are submitted as we continue to work on the project.

Upcoming Plans

Here are some higher-level initiatives that we are currently working on:

• Increase test coverage.
• Finish migration of using Algolia as a NoSQL database to PostgreSQL as the source of truth for all non-search data.