Self-Hosting osTicket with Docker Compose

What Is osTicket?

osTicket is an open-source support ticket system that routes customer inquiries from email, web forms, and phone into a single dashboard. It replaces Zendesk, Freshdesk, and Help Scout at zero cost. osTicket has been around since 2003 — it’s battle-tested, PHP-based, and runs on minimal hardware. It handles ticket assignment, SLA tracking, knowledge base articles, and auto-responses. Over 5 million downloads and 170,000+ businesses use it.

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 2 GB of RAM (minimum)
• 10 GB of free disk space
• A domain name (for customer-facing portal)
• SMTP credentials (for sending ticket notifications)

Docker Compose Configuration

osTicket requires a PHP application server and a MySQL/MariaDB database. The tiredofit/osticket image bundles Nginx + PHP-FPM and handles setup automatically.

Create a docker-compose.yml file:

services:
  osticket:
    image: tiredofit/osticket:1.18.3
    restart: unless-stopped
    depends_on:
      mariadb:
        condition: service_healthy
    ports:
      - "8080:80"
    environment:
      # Database connection
      - DB_HOST=mariadb
      - DB_PORT=3306
      - DB_NAME=osticket
      - DB_USER=osticket
      - DB_PASS=${DB_PASSWORD}
      - DB_PREFIX=ost_

      # Installation config — set once, keep stable
      - INSTALL_SECRET=${INSTALL_SECRET}
      - INSTALL_EMAIL=${INSTALL_EMAIL}
      - INSTALL_NAME=${INSTALL_NAME}
      - INSTALL_URL=${INSTALL_URL}

      # Admin account (created on first run)
      - ADMIN_FIRSTNAME=Admin
      - ADMIN_LASTNAME=Admin
      - ADMIN_EMAIL=${ADMIN_EMAIL}
      - ADMIN_USER=admin
      - ADMIN_PASS=${ADMIN_PASS}

      # SMTP for outgoing email
      - SMTP_HOST=${SMTP_HOST}
      - SMTP_PORT=${SMTP_PORT:-587}
      - SMTP_FROM=${SMTP_FROM}
      - SMTP_TLS=${SMTP_TLS:-1}
      - SMTP_USER=${SMTP_USER}
      - SMTP_PASS=${SMTP_PASS}

      # Email fetch interval (minutes)
      - CRON_INTERVAL=5

      - TZ=UTC
    volumes:
      - osticket-data:/www/osticket
      - osticket-logs:/www/logs
    networks:
      - osticket

  mariadb:
    image: mariadb:10.11
    restart: unless-stopped
    environment:
      - MYSQL_DATABASE=osticket
      - MYSQL_USER=osticket
      - MYSQL_PASSWORD=${DB_PASSWORD}
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
    volumes:
      - mariadb-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - osticket

volumes:
  osticket-data:
  osticket-logs:
  mariadb-data:

networks:
  osticket:
    driver: bridge

Create a .env file alongside:

# Database passwords — change both to strong random values
DB_PASSWORD=CHANGE_ME_STRONG_PASSWORD
MYSQL_ROOT_PASSWORD=CHANGE_ME_STRONG_ROOT_PASSWORD

# Installation config (set once, never change after first run)
# Generate: openssl rand -hex 16
INSTALL_SECRET=CHANGE_ME_GENERATE_ONCE
INSTALL_EMAIL=[email protected]
INSTALL_NAME=My Company Support
INSTALL_URL=https://support.example.com

# Admin account
ADMIN_EMAIL=[email protected]
ADMIN_PASS=CHANGE_ME_STRONG_PASSWORD

# SMTP — adjust for your email provider
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_FROM=[email protected]
SMTP_TLS=1
SMTP_USER=[email protected]
SMTP_PASS=your-app-password

Start the stack:

docker compose up -d

First startup takes 2-3 minutes while the database schema is created.

Initial Setup

1. Open http://your-server:8080 — the customer-facing ticket portal loads immediately
2. Access the Staff Control Panel at http://your-server:8080/scp/
3. Log in with the admin credentials from your .env file
4. Configure under Admin Panel → Settings:
   • Company: Organization name, website, logo
   • Emails: Verify outgoing email works (Admin → Emails → Diagnostic)
   • Departments: Create departments like “Support,” “Sales,” “Billing”
   • Help Topics: Define ticket categories customers see in the form

Access Point	URL
Customer portal	http://your-server:8080/
Staff panel	http://your-server:8080/scp/
Admin panel	http://your-server:8080/scp/admin.php

Configuration

Email Integration

osTicket can create tickets from incoming email. Under Admin Panel → Emails:

1. Add a new email address for receiving tickets
2. Configure IMAP/POP3 for fetching (server, port, credentials, SSL)
3. Set the fetch interval via CRON_INTERVAL (default: 5 minutes)
4. Map email addresses to departments for automatic routing

SLA Plans

Define response time commitments under Admin Panel → Manage → SLA Plans:

• Grace period: Hours before a ticket is marked overdue
• Schedule: Business hours or 24/7
• Escalation: What happens when SLA is breached

Ticket Filters

Auto-route tickets based on email address, subject, or content. Under Admin Panel → Manage → Ticket Filters:

• Match rules: email domain, subject keywords, custom fields
• Actions: assign department, set priority, add canned response, reject

Knowledge Base

osTicket includes a built-in FAQ/knowledge base. Under Staff Panel → Knowledgebase:

• Create categories and FAQ articles
• Link FAQs to help topics so customers see relevant articles before submitting tickets

Reverse Proxy

Place osTicket behind a reverse proxy for SSL. With Nginx Proxy Manager, proxy your domain to localhost:8080.

Update INSTALL_URL in your .env to match the public domain:

INSTALL_URL=https://support.example.com

For more details, see our Reverse Proxy Setup guide.

Backup

Back up both the database and attachment storage:

# Database dump
docker compose exec mariadb mysqldump -u root -p"${MYSQL_ROOT_PASSWORD}" osticket > osticket-backup-$(date +%Y%m%d).sql

# Attachment files
docker compose cp osticket:/www/osticket ./osticket-files-backup-$(date +%Y%m%d)/

Automate daily backups with cron. For a comprehensive strategy, see our Backup Strategy guide.

Troubleshooting

Setup Wizard Reappears After Restart

Symptom: Container restart triggers the installation wizard instead of loading the existing installation.

Fix: Set INSTALL_SECRET to a stable, persistent value in your .env file. This secret encrypts session data and identifies the installation. If it changes between restarts, osTicket thinks it’s a fresh install.

Email Notifications Not Sending

Symptom: Tickets are created but no email notifications go out.

Fix: Verify SMTP settings under Admin Panel → Emails → Diagnostic. Common issues:

• Gmail requires an App Password, not your regular password
• Port 587 with SMTP_TLS=1 for STARTTLS, or port 465 for implicit SSL
• Some providers block SMTP from cloud/VPS IP ranges

Large File Uploads Fail

Symptom: Attachments over 1-2 MB fail with a server error.

Fix: The Nginx config inside the container limits upload size. Override it by mounting a custom config or set the NGINX_CLIENT_MAX_BODY_SIZE environment variable if the image supports it. Also check the PHP upload_max_filesize setting.

Staff Panel Login Loop

Symptom: Logging into /scp/ redirects back to the login page.

Fix: This usually indicates a session/cookie issue. Ensure INSTALL_URL matches the exact URL you’re accessing (including https://). Clear browser cookies and retry.

Database Connection Errors

Symptom: “Unable to connect to database” on startup.

Fix: MariaDB takes 10-20 seconds to initialize. The healthcheck handles this, but if the issue persists, check credentials match between the osTicket and MariaDB containers:

docker compose logs mariadb
docker compose logs osticket

Resource Requirements

• RAM: 1 GB minimum, 2 GB recommended
• CPU: 1 core minimum (Low usage for small teams)
• Disk: 5 GB for the application, plus attachment storage

Component	RAM Usage
osTicket (Nginx + PHP-FPM)	~200-400 MB
MariaDB	~200-300 MB

osTicket is one of the lightest helpdesk systems you can self-host — it runs comfortably on a Raspberry Pi 4 or a $5/month VPS.

Verdict

osTicket is the best self-hosted helpdesk for small teams and budget-conscious organizations. It does one thing well: email-to-ticket conversion with agent assignment and SLA tracking. Setup takes minutes, it runs on minimal hardware, and the PHP codebase is mature and stable. The downside is that the interface looks dated compared to Zammad or FreeScout, and it lacks modern features like live chat integration or AI-powered responses. For teams that need multi-channel support (email + chat + social), Zammad is a better fit. For a lightweight, beautiful alternative to osTicket, try FreeScout. For straightforward email-based ticketing that just works, osTicket is hard to beat.

Related

• Best Self-Hosted Ticketing & Helpdesk
• OsTicket vs Zammad
• FreeScout vs Zammad
• Replace Zendesk with Self-Hosted Alternatives
• Docker Compose Basics
• Reverse Proxy Setup
• Backup Strategy