goatflow

module

v0.8.0 Latest Latest Go to latest Published: Mar 28, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/goatkit/goatflow

Links

Open Source Insights

README ¶

GoatFlow - Modern Open Source Ticketing System

GoatFlow is a GoatKit based ITSM system. It is a modern, secure, cloud-native ticketing and service management platform. Although it offers a seamless upgrade path for OTRS installations, it is built as a premier standalone solution for all organizations. Written in Go with a modular monolith architecture, GoatFlow provides enterprise-grade support ticketing, ITSM capabilities, and extensive customization options.

Key Features

🔒 Security-First Design - Built with zero-trust principles, comprehensive audit logging, enterprise security standards, and hardened plugin sandbox (OS-level isolation, ed25519 signing, SQL table whitelisting)
🚀 High Performance - Go-based backend with optimized database queries and caching
🌐 Cloud Native - Containerized deployment supporting Docker, Podman, and Kubernetes
📱 Responsive UI - Modern HTMX-powered interface with progressive enhancement
🔄 OTRS Compatible - Database schema superset enables seamless migration from OTRS 5.x and 6.x
🌍 Multi-Language - Full i18n with 15 languages at 100% coverage including RTL support, even supports Klingon! 🖖
🎨 Theme Engine - 4 distinct themes (Synthwave, Classic, 70s Vibes, 90s Vibe) with dark/light modes and custom fonts
🔌 Plugin Platform - Dual-runtime (WASM + gRPC) plugin system with sandboxed execution, hot reload, admin UI, ed25519 plugin signing, OS-level process isolation, SQL table whitelisting, and live policy updates
🔗 Extensible - REST/SOAP APIs, webhooks, and theme customization

Screenshot

Screenshot 1

Quick Start

Prerequisites

Docker with Compose plugin OR Docker Compose standalone OR Podman with Compose
Git
4GB RAM minimum
Modern web browser with JavaScript enabled

Container Runtime Support

GoatFlow is designed for container-first workflows and supports the following runtimes:

Docker Engine
- Docker Compose v1 (docker-compose) and v2 (Compose plugin: docker compose)
Podman
- Podman with Docker-compatible Compose (e.g. podman compose / podman-docker)
Rootless containers
- Supported for both Docker and Podman; may require additional host configuration for ports and volumes
SELinux-enabled hosts
- Volumes and bind mounts are compatible; use standard SELinux options/labels as required by your distribution

All make targets (for example, make up, make down, make restart) automatically detect whether Docker or Podman is available and choose the appropriate Compose command.

Using Containers (Auto-detected)

# Clone the repository
git clone https://github.com/goatkit/goatflow.git
cd goatflow

# Set up environment variables (REQUIRED - containers won't start without this!)
cp .env.development .env    # For local development (includes safe demo credentials)
# OR for production:
cp .env.example .env        # Then edit ALL values before use

# Start all services (auto-detects docker/podman compose command)
make up

# Alternative methods:
./scripts/compose.sh up          # Auto-detect wrapper script
docker compose up        # Modern Docker
docker-compose up        # Legacy Docker
podman compose up        # Podman plugin
podman-compose up        # Podman standalone

# Check which commands are available on your system
make debug-env

# Services will be available at:
# - Frontend: http://localhost
# - Backend API: http://localhost/api
# - smtp4dev (email sandbox): http://localhost:8025
# - Adminer (database UI): http://localhost:8090 (optional)

Development Workflow

# Start services in background
make up-d

# View logs
make backend-logs

# Run database migrations
make db-migrate

# Stop services
make down

# Reset everything (including database)
make clean

Podman on Fedora Kinoite/Silverblue

# Install podman-compose if needed
sudo rpm-ostree install podman-compose

# The Makefile auto-detects podman
make up

# Generate systemd units (Podman only)
make podman-systemd

Demo Instance

Try GoatFlow without installation at https://try.goatflow.io

Demo data resets daily

Testing

GoatFlow has comprehensive test coverage across multiple layers:

# Fast unit/integration tests (Alpine toolbox, ~1 minute)
make toolbox-test

# Full browser E2E tests (Ubuntu + Chromium, ~3-5 minutes)
make test-e2e-playwright-go

# Run all 1,200+ tests (5-8 minutes)
make test

Browser tests use Go + Playwright with the //go:build playwright tag and run in a dedicated Ubuntu container with Chromium. This separation keeps developer feedback fast while maintaining thorough browser coverage.

Architecture

GoatFlow uses a modern, hypermedia-driven architecture that scales from single-server deployments to large enterprise clusters:

Core Services: Authentication, Tickets, Users, Notifications, Workflow Engine
Data Layer: MariaDB/MySQL (default) or PostgreSQL, Valkey (cache), Zinc (search), S3-compatible storage (attachments)
API: RESTful JSON APIs with HTMX hypermedia endpoints
Frontend: HTMX + Alpine.js for progressive enhancement with Tailwind CSS
Workflow Engine: Temporal for complex business processes and automation
Real-time: Server-Sent Events (SSE) for live updates
Search: Zinc with Elasticsearch compatibility for full-text search

See ARCHITECTURE.md for detailed technical documentation.

Pluggable Authentication

Authentication supports an ordered provider list configured via the Auth::Providers setting in Config.yaml (default: [database]). Implemented providers:

database (agents + customer users from the database)
ldap (optional; enable with environment variables LDAP_ENABLED=true and related LDAP settings)
static (in-memory users for demos/tests)

Static users are enabled by setting the environment variable GOATFLOW_STATIC_USERS at runtime (NOT committed). Format:

GOATFLOW_STATIC_USERS="alice:password:Agent,bob:secret:Customer,carol:adminpass:Admin"

Notes:

Do not add this variable (or sample secrets) to committed .env files to avoid GitLeaks false positives.
Passwords may be plain or pre-hashed (bcrypt / legacy SHA from OTRS). The verifier auto-detects.
Omit the variable entirely to disable the static provider silently.

Provider resolution order: the system attempts each provider in the configured list until one authenticates or all fail.

Implementation note: the Auth::Providers list is read at startup via the unified configuration adapter; the main process wires this adapter into the auth service so changes to the list (after a restart) alter provider selection order without code changes.

Development Policies

Database access: This project uses database/sql with a thin database.ConvertPlaceholders wrapper to support PostgreSQL and MySQL. All SQL must be wrapped. See docs/development/DATABASE_ACCESS_PATTERNS.md.
Templating: Use Pongo2 templates exclusively. Do not use Go's html/template. Render user-facing views via Pongo2 with layouts/base.pongo2 and proper context.
Routing: Define all HTTP routes in YAML under routes/*.yaml using the YAML router. Do not register routes directly in Go code.
- YAML is the single source of truth for routes; hardcoded Gin registrations are prohibited.
- Health endpoints (including /healthz) are declared in YAML. Static files are served via YAML using handleStaticFiles.
- In test mode (APP_ENV=test), legacy admin hardcoded routes are skipped so SSR/YAML tests don’t double-register paths.
- YAML route loader is idempotent in dev/tests: it skips registering a route if the same method+path already exists and logs a dedupe message to avoid Gin panics.

SSR Smoke Tests

The SSR smoke test discovers GET routes with templates from YAML and ensures they render without 5xx errors.
Non-strict by default: logs 5xx; to fail on 5xx and on invalid/missing YAML-referenced templates, set SSR_SMOKE_STRICT=1.

CI/CD & Quality

GoatFlow maintains high code quality and security standards through comprehensive automated testing:

🔒 Security Pipeline

Vulnerability Scanning: Go (govulncheck), NPM dependencies (npm audit), container images (Trivy)
Static Analysis: Security (gosec, Semgrep), code quality (golangci-lint, ESLint)
Secret Detection: GitLeaks scans for accidentally committed secrets
License Compliance: Automated license checking for all dependencies
SAST: GitHub CodeQL for comprehensive static application security testing

🧪 Testing Pipeline

Unit Tests: Go backend with race detection, HTMX frontend
Integration Tests: End-to-end API testing with test database
Coverage: Automated coverage reporting via Codecov
Database: Full schema validation (MariaDB/PostgreSQL)

🚀 Build Pipeline

Multi-arch: AMD64 and ARM64 container builds
Supply Chain Security: SLSA Level 2 attestations, container signing
Automated Releases: Tagged releases with comprehensive release notes
Manual Builds: On-demand builds without registry pushing

📊 Quality Metrics

Comprehensive security scanning (8+ tools)
SLSA Level 2 compliant build process
Automated test coverage reporting via Codecov

Installation

System Requirements

Minimum (Development/Small Business)

2 CPU cores
4 GB RAM
20 GB storage
MariaDB 11+ or PostgreSQL 14+
Docker 20+ or Podman 3+

Recommended (Enterprise)

8+ CPU cores
16+ GB RAM
100+ GB SSD storage
MariaDB 11+ or PostgreSQL 14+ cluster
Kubernetes 1.24+

Production Deployment

For production deployments, see our comprehensive guides:

💡 Tip: Start with Docker deployment for single-server setups, then scale to Kubernetes as your needs grow.

Documentation

User Guides

Technical Documentation

Additional Resources

Migration from OTRS

GoatFlow maintains database schema compatibility with OTRS, enabling migration from existing installations. The goatflow-migrate tool handles database import from OTRS 5.x and 6.x SQL dumps.

# Analyze your OTRS dump
make migrate-analyze SQL=/path/to/otrs_dump.sql

# Test import (dry run)
make migrate-import SQL=/path/to/otrs_dump.sql DRY_RUN=true

# Execute import
make migrate-import SQL=/path/to/otrs_dump.sql DRY_RUN=false

# Validate migrated data
make migrate-validate

The migration tool imports tickets, articles, users, customers, queues, and configuration data. Article attachments require a separate filesystem copy.

See docs/MIGRATION.md for the complete migration guide.

Internationalization (i18n)

GoatFlow provides comprehensive multi-language support:

Language Support

Language	Code	Direction	Status
English	en	LTR	✅ Base Language
Arabic	ar	RTL	✅ Complete
Chinese	zh	LTR	✅ Complete
French	fr	LTR	✅ Complete
German	de	LTR	✅ Complete
Hebrew	he	RTL	✅ Complete
Japanese	ja	LTR	✅ Complete
Persian	fa	RTL	✅ Complete
Polish	pl	LTR	✅ Complete
Portuguese	pt	LTR	✅ Complete
Russian	ru	LTR	✅ Complete
Spanish	es	LTR	✅ Complete
Ukrainian	uk	LTR	✅ Complete
Urdu	ur	RTL	✅ Complete
Klingon	tlh	LTR	✅ Complete (Qapla'! 🖖)

i18n Features

Embedded translations - JSON files compiled into the binary for zero-config deployment
RTL support - Full right-to-left language support (Arabic, Hebrew, Persian, Urdu)
User preferences - Language selection persisted per-user in profile settings
Locale formatting - Date, time, number, and currency formatting per language
Validation tests - Automated coverage testing ensures 100% translation completeness

Adding New Languages

Create translation file: internal/i18n/translations/xx.json
Add language config to internal/i18n/rtl.go (single source of truth)
Run tests: make test-i18n
Rebuild: make build

See i18n Contributing Guide for detailed instructions.

Features Comparison

See FEATURES.md for a comprehensive comparison matrix of GoatFlow vs OTRS, Zendesk, and ServiceNow across 19 feature categories including:

✅ Core ticketing, email integration, knowledge base
✅ Theme engine with 4 built-in themes and dark mode
✅ Cloud native, air-gapped deployment, 15 languages
✅ REST API, source code access, self-hosted

Roadmap

See ROADMAP.md for the development timeline and planned features.

Contributing

See our Contributing Guide for details on:

Code of Conduct
Development setup
Coding standards
Pull request process
Issue reporting

For AI/Agent Contributors: See docs/development/AGENT_GUIDE.md for the canonical operating manual.

Community

License

GoatFlow Community Edition is licensed under the Apache License 2.0.

For enterprise licensing options, see LICENSING.md.

Support

Community Support

See the Community section above for forums, chat, and issue tracking.

Commercial Support

Professional support contracts
Implementation services
Custom development
Training and certification

Contact: hello@goatflow.io

Security

Security is our top priority. Please report security vulnerabilities to security@goatflow.io.

See SECURITY.md for our security policies and practices.

Legal and Compatibility Notice

GoatFlow-CE is an independent, original implementation of a ticket management system. While we maintain database compatibility for interoperability purposes, all code is originally written. We are not affiliated with OTRS AG. See LEGAL.md for important legal information.

Acknowledgments

GoatFlow builds upon decades of open source ticketing system innovation. We acknowledge the contributions of the OTRS community and other open source projects that have paved the way.

GoatFlow - Enterprise Ticketing, Community Driven

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
add-ticket-translations command Package main provides a tool for adding ticket translations.	Package main provides a tool for adding ticket translations.
add-translations command Package main provides a tool for adding translations.	Package main provides a tool for adding translations.
contract-runner command Package main provides the contract test runner.	Package main provides the contract test runner.
generator command Package main provides code generation utilities.	Package main provides code generation utilities.
gk command Package main provides the GoatKit CLI tool for plugin development.	Package main provides the GoatKit CLI tool for plugin development.
goatflow command Package main provides the GoatFlow server application.	Package main provides the GoatFlow server application.
goatflow-babelfish command Package main provides translation file processing.	Package main provides translation file processing.
goatflow-config command Package main provides configuration management utilities.	Package main provides configuration management utilities.
goatflow-db command Package main provides database utilities.	Package main provides database utilities.
goatflow-migrate command Package main provides fixed import utilities for migration.	Package main provides fixed import utilities for migration.
goatflow-storage command Package main provides storage management utilities.	Package main provides storage management utilities.
goats command
route-docs command Package main provides route documentation generation.	Package main provides route documentation generation.
route-lint command Package main provides route linting utilities.	Package main provides route linting utilities.
route-test command Package main provides route testing utilities.	Package main provides route testing utilities.
route-version command Package main provides route version management.	Package main provides route version management.
routes-diff command Package main provides route diff utilities.	Package main provides route diff utilities.
routes-manifest command Package main provides route manifest generation.	Package main provides route manifest generation.
schema-discovery command Package main provides schema discovery utilities.	Package main provides schema discovery utilities.
test_i18n command Package main provides i18n testing utilities.	Package main provides i18n testing utilities.
test_lookups command Package main provides lookup testing utilities.	Package main provides lookup testing utilities.
test_xlat command Package main provides translation testing utilities.	Package main provides translation testing utilities.
xlat-extract command Package main provides translation extraction.	Package main provides translation extraction.
docs
api Package api Code generated by swaggo/swag.	Package api Code generated by swaggo/swag.
internal
api Package api provides HTTP handlers for the GoatFlow application.	Package api provides HTTP handlers for the GoatFlow application.
api/shared Package api provides shared API handlers and utilities for article creation.	Package api provides shared API handlers and utilities for article creation.
api/v1
apierrors Package apierrors provides structured API error codes and responses.	Package apierrors provides structured API error codes and responses.
auth Package auth provides authentication and JWT token handling.	Package auth provides authentication and JWT token handling.
cache Package cache provides caching utilities including compression support.	Package cache provides caching utilities including compression support.
components/dashboard Package dashboard provides real-time dashboard components and handlers.	Package dashboard provides real-time dashboard components and handlers.
components/dynamic Package dynamic provides dynamic component rendering and field handling.	Package dynamic provides dynamic component rendering and field handling.
components/handlers Package handlers provides base CRUD handlers for component operations.	Package handlers provides base CRUD handlers for component operations.
components/lambda Package lambda provides JavaScript execution capabilities for dynamic modules	Package lambda provides JavaScript execution capabilities for dynamic modules
config Package config provides application configuration management.	Package config provides application configuration management.
constants Package constants provides application-wide constant definitions.	Package constants provides application-wide constant definitions.
convert Package convert provides type conversion utilities.	Package convert provides type conversion utilities.
core Package core provides core business logic for article type resolution.	Package core provides core business logic for article type resolution.
customfields Package customfields implements GoatKit PaaS Core universal custom fields.	Package customfields implements GoatKit PaaS Core universal custom fields.
data Package data provides data access repositories for lookup tables.	Package data provides data access repositories for lookup tables.
database Package database provides database connection and adapter management.	Package database provides database connection and adapter management.
database/drivers/mysql Package mysql provides the MySQL database driver implementation.	Package mysql provides the MySQL database driver implementation.
database/drivers/postgres Package postgres provides the PostgreSQL database driver implementation.	Package postgres provides the PostgreSQL database driver implementation.
database/drivers/sqlite Package sqlite provides the SQLite database driver implementation.	Package sqlite provides the SQLite database driver implementation.
database/schema Package schema provides database schema loading and management.	Package schema provides database schema loading and management.
deletion Package deletion implements the GoatKit PaaS Entity Deletion system.	Package deletion implements the GoatKit PaaS Entity Deletion system.
email Package email provides email handling and processing utilities.	Package email provides email handling and processing utilities.
email/inbound/adapter Package adapter provides mail account adapters for inbound email processing.	Package adapter provides mail account adapters for inbound email processing.
email/inbound/connector Package connector provides email server connection interfaces and implementations.	Package connector provides email server connection interfaces and implementations.
email/inbound/filters Package filters provides email filter annotations and processing rules.	Package filters provides email filter annotations and processing rules.
email/inbound/postmaster Package postmaster provides email parsing, filtering, and dispatch orchestration.	Package postmaster provides email parsing, filtering, and dispatch orchestration.
history Package history provides ticket history formatting and display utilities.	Package history provides ticket history formatting and display utilities.
i18n
ldap Package ldap provides LDAP authentication and directory service integration.	Package ldap provides LDAP authentication and directory service integration.
lookups Package lookups provides static lookup data including country codes.	Package lookups provides static lookup data including country codes.
mailaccountmeta Package mailaccountmeta provides mail account metadata parsing and serialization.	Package mailaccountmeta provides mail account metadata parsing and serialization.
mailqueue Package mailqueue provides email queue storage and management.	Package mailqueue provides email queue storage and management.
marketplace Package marketplace provides plugin discovery, installation, and update functionality using GitHub Releases as the distribution backend.	Package marketplace provides plugin discovery, installation, and update functionality using GitHub Releases as the distribution backend.
mcp Package mcp implements the Model Context Protocol server for GoatFlow.	Package mcp implements the Model Context Protocol server for GoatFlow.
middleware Package middleware provides HTTP middleware for authentication and authorization.	Package middleware provides HTTP middleware for authentication and authorization.
models Package models provides domain models and data structures.	Package models provides domain models and data structures.
notifications Package notifications provides notification context and delivery management.	Package notifications provides notification context and delivery management.
oauth2 Package oauth2 provides OAuth2 authentication provider implementations.	Package oauth2 provides OAuth2 authentication provider implementations.
organisation Package organisation implements GoatKit PaaS Core multi-tenancy.	Package organisation implements GoatKit PaaS Core multi-tenancy.
platform/schema Package schema provides database schema discovery and introspection.	Package schema provides database schema discovery and introspection.
plugin Package plugin re-exports the public plugin types from pkg/plugin.	Package plugin re-exports the public plugin types from pkg/plugin.
plugin/core Package core provides core built-in plugins for GoatFlow.	Package core provides core built-in plugins for GoatFlow.
plugin/example Package example provides example plugin implementations for testing.	Package example provides example plugin implementations for testing.
plugin/grpc Package grpc provides gRPC-based plugin runtime using HashiCorp go-plugin.	Package grpc provides gRPC-based plugin runtime using HashiCorp go-plugin.
plugin/grpc/example command Example gRPC plugin for GoatKit.	Example gRPC plugin for GoatKit.
plugin/loader
plugin/packaging Package packaging provides ZIP-based plugin packaging and extraction.	Package packaging provides ZIP-based plugin packaging and extraction.
plugin/signing
plugin/wasm Package wasm provides a WASM-based plugin runtime using wazero.	Package wasm provides a WASM-based plugin runtime using wazero.
pluginui Package pluginui implements the GoatKit PaaS Plugin UI System.	Package pluginui implements the GoatKit PaaS Plugin UI System.
repository Package repository provides data access repositories for domain entities.	Package repository provides data access repositories for domain entities.
repository/memory Package memory provides in-memory repository implementations for testing.	Package memory provides in-memory repository implementations for testing.
routing Package routing provides HTTP routing and analytics endpoints.	Package routing provides HTTP routing and analytics endpoints.
runner Package runner provides background task runner and lifecycle management.	Package runner provides background task runner and lifecycle management.
runner/tasks Package tasks provides background task implementations for the runner.	Package tasks provides background task implementations for the runner.
search Package search provides search backend implementations including Elasticsearch.	Package search provides search backend implementations including Elasticsearch.
secureconfig Package secureconfig provides encrypted key-value storage for plugin secrets.	Package secureconfig provides encrypted key-value storage for plugin secrets.
selfservice Package selfservice implements self-service authentication: password recovery, customer registration, email verification, and CAPTCHA.	Package selfservice implements self-service authentication: password recovery, customer registration, email verification, and CAPTCHA.
service Package service provides business logic services for the application.	Package service provides business logic services for the application.
service/genericinterface Package genericinterface provides the GenericInterface service for web service execution.	Package genericinterface provides the GenericInterface service for web service execution.
service/ticket_number Package ticket_number provides ticket number generation strategies.	Package ticket_number provides ticket number generation strategies.
services
services/acl Package acl provides the ACL (Access Control List) execution engine.	Package acl provides the ACL (Access Control List) execution engine.
services/adapter Package adapter provides service adapters for database operations.	Package adapter provides service adapters for database operations.
services/database Package database provides database service interfaces and implementations.	Package database provides database service interfaces and implementations.
services/escalation Package escalation provides SLA escalation calculation and management.	Package escalation provides SLA escalation calculation and management.
services/genericagent Package genericagent provides the Generic Agent execution engine.	Package genericagent provides the Generic Agent execution engine.
services/k8s Package k8s provides Kubernetes environment detection and integration.	Package k8s provides Kubernetes environment detection and integration.
services/registry Package registry provides service registration and lifecycle management.	Package registry provides service registration and lifecycle management.
services/scheduler Package scheduler provides task scheduling and job management.	Package scheduler provides task scheduling and job management.
services/ticket Package ticket provides ticket domain models and business logic.	Package ticket provides ticket domain models and business logic.
services/ticketattributerelations Package ticketattributerelations provides management of ticket attribute relationships.	Package ticketattributerelations provides management of ticket attribute relationships.
services/user Package user provides user domain models and management.	Package user provides user domain models and management.
shared Package shared provides shared types and utilities across packages.	Package shared provides shared types and utilities across packages.
storage Package storage provides article attachment storage backends.	Package storage provides article attachment storage backends.
sysconfig Package sysconfig provides system configuration management.	Package sysconfig provides system configuration management.
template
testing/contracts Package contracts provides API contract definitions for integration testing.	Package contracts provides API contract definitions for integration testing.
testutil Package testutil provides testing utilities and test environment setup.	Package testutil provides testing utilities and test environment setup.
ticketnumber Package ticketnumber provides ticket number generation implementations.	Package ticketnumber provides ticket number generation implementations.
ticketutil Package ticketutil provides utility functions for ticket operations.	Package ticketutil provides utility functions for ticket operations.
utils Package utils provides utility functions including HTML sanitization.	Package utils provides utility functions including HTML sanitization.
version Package version provides build-time version information for GoatFlow.	Package version provides build-time version information for GoatFlow.
webhook Package webhook provides webhook delivery and management.	Package webhook provides webhook delivery and management.
webhooks Package webhooks provides webhook event types and payload definitions.	Package webhooks provides webhook event types and payload definitions.
yamlmgmt
zinc Package zinc provides the ZincSearch client for full-text search.	Package zinc provides the ZincSearch client for full-text search.
pkg
plugin Package plugin defines the unified interface for GoatKit plugins.	Package plugin defines the unified interface for GoatKit plugins.
plugin/grpcutil Package grpcutil provides shared types for gRPC plugin communication.	Package grpcutil provides shared types for gRPC plugin communication.
tests
e2e/config
e2e/helpers
tools
test-utilities/example-migration command Package main provides an example migration tool for testing schema migrations.	Package main provides an example migration tool for testing schema migrations.
test-utilities/test-db-abstraction command Package main provides test utilities for validating the database abstraction layer.	Package main provides test utilities for validating the database abstraction layer.
test-utilities/test-password-hash command Package main provides test utilities for password hashing and OTRS compatibility.	Package main provides test utilities for password hashing and OTRS compatibility.