gotrs-ce

module

v0.5.1 Latest Latest Go to latest Published: Jan 8, 2026 License: Apache-2.0

Details

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

Repository

github.com/gotrs-io/gotrs-ce

Links

Open Source Insights

README ¶

GOTRS - Modern Open Source Ticketing System

GOTRS (Go Open Ticket Request System) is a modern, secure, cloud-native ticketing and service management platform built as a next-generation replacement for OTRS. Written in Go with a modular monolith architecture, GOTRS provides enterprise-grade support ticketing, ITSM capabilities, and extensive customization options.

Key Features

🔒 Security-First Design - Built with zero-trust principles, comprehensive audit logging, and enterprise security standards
🚀 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
- ⚠️ Unicode Support: Configure with UNICODE_SUPPORT=true for full Unicode support (requires utf8mb4 migration)
🌍 Multi-Language - Full i18n with German 100% complete, even supports Klingon! 🖖
🎨 Themeable - Customizable UI with dark/light modes and branding options
🔌 Extensible - Plugin framework for custom modules and integrations

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:

✅ Docker with docker compose plugin (v2) - Recommended
✅ docker-compose standalone (v1) - Legacy support
✅ Podman with podman compose plugin
✅ podman-compose standalone
✅ Full rootless container support
✅ SELinux labels configured for Fedora/RHEL systems

Using Containers (Auto-detected)

# Clone the repository
git clone https://github.com/gotrs-io/gotrs-ce.git
cd gotrs-ce

# 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 GOTRS without installation at https://try.gotrs.io

Demo credentials are shown on the demo instance login page.

Note: Demo data resets daily at 2 AM UTC

Browser E2E (Go + Playwright)

We separate backend/API tests from full browser automation:

Toolbox targets (make toolbox-test, make toolbox-test-api) intentionally skip heavy browser tests.
Browser-driven Go tests are tagged with playwright (see //go:build playwright).
Run them in a dedicated Playwright image (Ubuntu base) to avoid glibc/musl issues:

make test-e2e-playwright-go        # Builds Dockerfile.playwright-go and runs go test -tags playwright ./tests/e2e

Standard JavaScript-based Playwright tests (if present) continue to use make test-e2e-playwright which wraps docker-compose.playwright.yml.

Rationale: the lightweight Alpine toolbox keeps feedback fast; heavyweight Chromium dependencies stay isolated.

Architecture

GOTRS 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 GOTRS_STATIC_USERS at runtime (NOT committed). Format:

GOTRS_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 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

GOTRS 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

All pipelines complete in under 10 minutes
Zero-cost (GitHub Actions free tier + open source tools)
Comprehensive security scanning (8+ tools)
SLSA Level 2 compliant build process
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:

Documentation

Configuration System: docs/configuration.md
Ticket Number Generators: docs/ticket_number_generators.md
YAML Platform: docs/YAML_PLATFORM.md
Architecture: ARCHITECTURE.md
Roadmap: ROADMAP.md
Getting Started Guide
Administrator Manual
Agent Manual
Developer Guide
API Reference
i18n Contributing Guide

Migration from OTRS

GOTRS provides comprehensive migration tools for OTRS users:

# Run the migration tool in a container
docker-compose exec backend /app/tools/otrs-migration/migrate \
  --source-db "postgres://otrs_user:pass@old-server/otrs" \
  --target-db "postgres://postgres:5432/gotrs" \
  --validate

# Or using a dedicated migration container
docker run --rm \
  --network gotrs-network \
  -v ./data:/data:Z \
  gotrs/migration-tool:latest \
  --source-db "postgres://otrs_user:pass@old-server/otrs" \
  --target-db "postgres://postgres:5432/gotrs" \
  --validate

See Migration Guide for detailed instructions.

Internationalization (i18n)

GOTRS provides comprehensive multi-language support with developer-friendly tools:

Language Support

English (en) - 100% complete (base language)
German (de) - 100% complete
Klingon (tlh) - 39% complete (Yes, really! 🖖)
Spanish (es) - 47% complete
French (fr) - In progress
Portuguese (pt) - In progress
Japanese (ja) - In progress
Chinese (zh) - In progress
More languages coming soon!

i18n Features

API-driven translation management - RESTful endpoints for coverage, validation, import/export
CLI tools - Command-line utilities for translation workflows
Live language switching - Change language without page reload using ?lang=xx
Translation validation - Automatic completeness checking and key validation
CSV/JSON export - Easy integration with translation services
TDD approach - All i18n features developed with test-driven development

For Contributors - Using gotrs-babelfish 🐠

# Check translation coverage (with Hitchhiker's Guide style!)
make babelfish-coverage

# Find missing translations (even for Klingon!)
make babelfish-missing LANG=tlh

# Validate translations
make babelfish-validate LANG=de

# Run with custom options (Don't Panic!)
docker exec gotrs-backend go run cmd/gotrs-babelfish/main.go -help

# Use API for coverage stats
curl http://localhost:8080/api/v1/i18n/coverage

# Test the UI in Klingon (Qapla'!)
# http://localhost:8080/dashboard?lang=tlh

gotrs-babelfish: Named after the Babel fish from The Hitchhiker's Guide to the Galaxy - stick it in your ear and instantly understand any language!

See i18n Contributing Guide for detailed instructions on adding new languages.

Features Comparison

Feature	GOTRS	OTRS	Zendesk	ServiceNow
Open Source	✅ (Apache 2.0)	✅ (GPL)	❌	❌
Self-Hosted	✅	✅	❌	✅
Cloud Native	✅	❌	✅	✅
Modern UI	✅	❌	✅	✅
REST API	✅	✅	✅	✅
GraphQL API	📋 (Future)	❌	❌	✅
Microservices	📋 (Future)	❌	✅	✅
Plugin System	📋 (Future)	✅	✅	✅
ITSM Modules	📋 (Future)	✅	❌	✅
Multi-Language	✅ (EN/DE/FR/ES/AR)	✅	✅	✅

Roadmap

Current Phase: MVP Development (Starting August 2025)

🚧 Core ticketing functionality
🚧 User authentication and authorization
✅ Email threading (RFC-compliant Message-ID, In-Reply-To, References)
📋 Basic reporting
📋 Docker deployment

Upcoming Phases

Q4 2025: Essential features, Production-ready deployment
Q1 2026: Advanced workflows, API v1, Plugin framework
Q2 2026: ITSM modules, Advanced reporting, Mobile apps
Q3 2026: AI/ML features, Enterprise features
Q4 2026: Platform maturity, Cloud SaaS launch

See ROADMAP.md for detailed development timeline.

Contributing

Engineering assistants: See AGENT.md for the canonical operating manual. Developers: See CONTRIBUTING.md for contribution process and standards.

We welcome contributions! Please see our Contributing Guide for details on:

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

Community

License

GOTRS is dual-licensed:

Community Edition: Apache License 2.0
Enterprise Edition: Commercial License

See LICENSING.md for details on our dual licensing model.

Support

Community Support

GitHub Issues
Discord Community
Community Forums

Commercial Support

Professional support contracts
Implementation services
Custom development
Training and certification

Contact: support@gotrs.io

Security

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

See SECURITY.md for our security policies and practices.

Legal and Compatibility Notice

GOTRS-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

GOTRS 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.

GOTRS - 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 GK command-line tool.	Package main provides the GK command-line tool.
goats command Package main provides the GOATS CLI tool.	Package main provides the GOATS CLI tool.
gotrs command Package main provides the GOTRS server application.	Package main provides the GOTRS server application.
gotrs-babelfish command Package main provides translation file processing.	Package main provides translation file processing.
gotrs-config command Package main provides configuration management utilities.	Package main provides configuration management utilities.
gotrs-db command Package main provides database utilities.	Package main provides database utilities.
gotrs-migrate command Package main provides fixed import utilities for migration.	Package main provides fixed import utilities for migration.
gotrs-storage command Package main provides storage management utilities.	Package main provides storage management utilities.
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.
internal
api Package api provides HTTP handlers for the GOTRS application.	Package api provides HTTP handlers for the GOTRS 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
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.
core Package core provides core business logic for article type resolution.	Package core provides core business logic for article type resolution.
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.
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.
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.
platform/schema Package schema provides database schema discovery and introspection.	Package schema provides database schema discovery and introspection.
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.
service Package service provides business logic services for the application.	Package service provides business logic services for the application.
service/ticket_number Package ticket_number provides ticket number generation strategies.	Package ticket_number provides ticket number generation strategies.
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/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/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.
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 GOTRS.	Package version provides build-time version information for GOTRS.
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.
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.