GitHub Get Started

Getting Started

Quick start guide for installing and setting up GOTRS.

Getting Started with GOTRS

Get GOTRS up and running quickly with Docker or Podman.

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

Quick Start

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
# - Mailhog (email testing): 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

What’s Included

  • PostgreSQL: Primary database (OTRS-compatible schema)
  • Valkey: Caching and sessions (Redis-compatible)
  • Backend: Go API server (goats binary) with HTMX endpoints
  • Frontend: HTMX + Alpine.js with server-side rendering
  • Nginx: Reverse proxy
  • MailHog: Email testing (development)

Architecture

GOTRS uses a modern, hypermedia-driven architecture:

  • Core Services: Authentication, Tickets, Users, Notifications, Workflow Engine
  • Data Layer: PostgreSQL (primary), 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

Next Steps

  1. Complete Installation: Follow the full setup guide
  2. Initial Configuration: Configure your GOTRS instance
  3. User Setup: Create admin users and configure authentication
  4. Email Setup: Configure SMTP for production

Need Help?

Check out our support page for community help and professional services.