Hermes

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

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

🚀 Quick Start

Get Hermes running locally in one command:

```bash cd testing && docker compose up -d ```

This starts a complete testing environment with:

• ✅ Backend (Go) on http://localhost:8001
• ✅ Frontend (Ember.js) on http://localhost:4201
• ✅ PostgreSQL database
• ✅ Meilisearch search engine
• ✅ Dex OIDC provider

Login: test@hermes.local / password

Alternative: Native Development

For faster iteration when developing backend or frontend code:

```bash

1. Copy example configuration

cp config-example.hcl config.hcl

2. Start infrastructure services only

cd testing && docker compose up -d postgres meilisearch dex && cd ..

3. Terminal 1: Backend

make bin ./hermes server -config=config.hcl

4. Terminal 2: Frontend

cd web && yarn install yarn start:proxy # Auto-detects backend on port 8000

5. Open http://localhost:4200

```

Next Steps:

• 📖 Testing Environment Guide - Detailed setup and troubleshooting
• 🔧 Configuration Guide - Customize your setup
• 🧪 Makefile Targets - Common development commands

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Users / Browsers                         │
└───────────────────────────┬─────────────────────────────────────┘
                            │ HTTPS
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Frontend (Ember.js)                          │
│  • TypeScript + Tailwind CSS + HashiCorp Design System         │
│  • Document editor, search UI, approval workflows              │
└───────────────────────────┬─────────────────────────────────────┘
                            │ API Calls
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Backend (Go Server)                          │
│  • REST API (v1 + v2)                                          │
│  • Authentication & Authorization                               │
│  • Document lifecycle management                               │
│  • Search proxy                                                 │
└─────┬──────────┬──────────┬────────────┬────────────────────────┘
      │          │          │            │
      ▼          ▼          ▼            ▼
┌──────────┐ ┌────────┐ ┌────────┐ ┌─────────────┐
│PostgreSQL│ │Workspace│ │ Search │ │    Auth     │
│          │ │Provider │ │Provider│ │  Provider   │
│  (GORM)  │ │         │ │        │ │             │
└──────────┘ └────────┘ └────────┘ └─────────────┘
      │          │          │            │
      │     ┌────┴────┐ ┌───┴────┐  ┌────┴─────┐
      │     │ Google  │ │Algolia │  │  Google  │
      │     │Workspace│ │   or   │  │  OAuth   │
      │     │   or    │ │Meili   │  │    or    │
      │     │  Local  │ │ search │  │ Okta/Dex │
      │     └─────────┘ └────────┘  └──────────┘
      │
      ▼
┌─────────────────┐
│   Indexer       │
│ (Background)    │
│ • Syncs docs    │
│ • Updates index │
│ • Updates headers│
└─────────────────┘

Components

Frontend: Ember.js 6.7 TypeScript application with HDS components
Backend: Go 1.25+ server with modular provider architecture
Database: PostgreSQL 15+ (source of truth for all data)
Search: Algolia (managed) or Meilisearch (self-hosted)
Workspace: Google Workspace (production) or Local (development)
Auth: Google OAuth, Okta OIDC, or Dex (local)

See Architecture Documentation for details.

📋 Requirements

• Go: 1.25 or later
• Node.js: 20 or later
• Yarn: 4.10+ (install with corepack)
• Docker & Docker Compose: For local services (PostgreSQL, Dex, Meilisearch)

🔌 Provider Configuration

Hermes uses a modular provider architecture. Configure providers in config.hcl:

providers {
  auth      = "dex"          # or "google", "okta"
  workspace = "local"        # or "google"
  search    = "meilisearch"  # or "algolia"
}

Provider Guides

Authentication Providers:

• 🔐 Dex (Local) - Recommended for development
• 🔐 Google OAuth - Production with Workspace
• 🔐 Okta - Enterprise SSO

Workspace Providers (document storage):

• 📁 Local Workspace - Filesystem-based, for development
• 📁 Google Workspace - Google Docs integration

Search Providers:

• 🔍 Meilisearch - Self-hosted, open-source
• 🔍 Algolia - Managed, cloud-hosted

Infrastructure:

• 🗄️ PostgreSQL - Primary database
• 🎫 Jira Integration - Optional project linking

🛠️ Development

Build Commands

# Backend only (fast)
make bin

# Backend tests
make go/test

# Frontend (in web/)
cd web
yarn install
yarn test:types      # TypeScript checking
yarn lint:hbs        # Template linting
yarn build           # Production build

# Full build (backend + frontend)
make build

Development Modes

Option 1: Native Backend + Native Frontend (fastest iteration)

# Terminal 1: Backend
make bin && ./hermes server -config=config.hcl

# Terminal 2: Frontend
cd web && yarn start:proxy

Option 2: Docker Backend + Native Frontend (stable backend, fast frontend)

# Start backend in Docker
cd testing && docker compose up -d

# Frontend in another terminal
cd web && yarn start:proxy:testing

Option 3: Fully Containerized (complete integration)

# Everything in containers
cd testing && docker compose up -d

# Access at http://localhost:4201

See Makefile Targets Guide for all available commands.

Configuration

The config-example.hcl file contains comprehensive documentation for all options:

# Copy and customize
cp config-example.hcl config.hcl
nano config.hcl

# Start with your config
./hermes server -config=config.hcl

See Configuration Documentation for details.

🧪 Testing

End-to-End Tests

# Start services first
cd testing && docker compose up -d

# Run Playwright tests
cd tests/e2e-playwright
npx playwright test --reporter=line

See Playwright Guide for comprehensive testing instructions.

Unit Tests

# Backend tests (no DB required)
make go/test

# Frontend tests
cd web && yarn test:types

📚 Documentation

Getting Started

• Testing Environment - Complete local setup
• Configuration Guide - All config options
• Makefile Targets - Development workflows

Provider Setup

• Dex Authentication - Local auth for development
• Google Workspace - Production document storage
• Local Workspace - Filesystem-based storage
• Meilisearch - Self-hosted search
• Algolia - Managed search
• PostgreSQL - Database setup
• Jira Integration - Project management integration

Architecture & Development

• Auth Providers Overview - All authentication options
• Architecture Diagrams - System design
• ADRs - Architecture decisions
• RFCs - Technical proposals
• Agent Instructions - AI-assisted development

🚢 Production Deployment

Typical Production Stack

providers {
  auth      = "google"    # or "okta"
  workspace = "google"    # Google Workspace
  search    = "algolia"   # or self-hosted Meilisearch
}

# Use managed PostgreSQL (RDS, Cloud SQL, etc.)
# Configure SSL/TLS for all connections
# Use environment variables for secrets
# Enable structured logging

Production Checklist

• Configure authentication provider (Google/Okta)
• Set up Google Workspace with service account
• Configure search provider (Algolia or Meilisearch)
• Deploy managed PostgreSQL with backups
• Set log_format = "json" in config.hcl
• Use environment variables for secrets
• Configure base_url to your public URL
• Set up SSL/TLS certificates
• Enable monitoring and alerting
• Run indexer as background service

📊 Project Status

This project is under active development and in the alpha stage. There may be breaking changes to:

• API endpoints
• Configuration file format
• Database schema
• Provider interfaces

We recommend:

• ✅ Using for internal tools and testing
• ✅ Following releases for updates
• ❌ Avoid production use until beta/stable
• ❌ Don't install builds from main branch

See GitHub Releases for stable versions.

🤝 Contributing

Before submitting a PR, please create a GitHub issue to discuss your proposed changes. This ensures alignment with project direction and avoids conflicts with planned work.

Note: Response time may be up to one week as we continue active development.

💬 Feedback

• Security issues: Email security@hashicorp.com (do not file public issues)
• Bugs & features: Open a GitHub issue
• Questions: Check documentation or open a discussion

📜 License

See LICENSE file for details.

---

Maintained by: HashiCorp Labs (Office of the CTO)
Status: Alpha - Active Development
Website: https://hashicorp.com/blog/introducing-hermes-an-open-source-document-management-system