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=support@example.com
INSTALL_NAME=My Company Support
INSTALL_URL=https://support.example.com

# Admin account
ADMIN_EMAIL=admin@example.com
ADMIN_PASS=CHANGE_ME_STRONG_PASSWORD

# SMTP — adjust for your email provider
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_FROM=support@example.com
SMTP_TLS=1
SMTP_USER=your-email@gmail.com
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

Open http://your-server:8080 — the customer-facing ticket portal loads immediately
Access the Staff Control Panel at http://your-server:8080/scp/
Log in with the admin credentials from your .env file
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:

Add a new email address for receiving tickets
Configure IMAP/POP3 for fetching (server, port, credentials, SSL)
Set the fetch interval via CRON_INTERVAL (default: 5 minutes)
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.

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.

Frequently Asked Questions

How does osTicket compare to Zendesk?

osTicket covers the core helpdesk functionality — email-to-ticket conversion, agent assignment, SLA tracking, canned responses, and a knowledge base. Zendesk adds live chat, AI-powered routing, advanced analytics, and 1,000+ app integrations. osTicket is free and self-hosted; Zendesk starts at $19/agent/month. For small teams that primarily handle email-based support, osTicket does the job. For multi-channel support at scale, Zendesk or self-hosted Zammad is more appropriate.

Can osTicket convert emails directly into tickets?

Yes — this is osTicket’s core strength. Configure email piping or IMAP/POP3 fetching in the admin panel, and emails sent to your support address automatically create tickets. Customer replies to ticket notifications update the existing ticket thread. Agents manage everything from the web interface without touching email clients.

Does osTicket support multiple departments?

Yes. Create separate departments (Sales, Support, Billing) with different SLA policies, auto-assignment rules, and escalation paths. Each department can have its own email address. Tickets can be transferred between departments. Department-level permissions control which agents see which tickets.

Is osTicket suitable for ITIL/IT service management?

osTicket handles basic incident and request management. It lacks ITIL-specific features like change management, asset management, CMDB, and problem management that tools like GLPI or iTop provide. For pure helpdesk ticketing (support emails → organized response workflow), osTicket is excellent. For formal ITIL processes, look at dedicated ITSM tools.

Can I customize the customer-facing portal?

Yes. osTicket includes a customer portal where users can submit and track tickets. The portal theme is customizable through template files and CSS. You can add custom ticket forms with different fields per help topic (e.g., “Bug Report” with severity dropdown, “Feature Request” with a description field). The portal supports multiple languages.

How do I migrate from another helpdesk to osTicket?

There’s no automated migration tool for most platforms. The standard approach is to export tickets as CSV from your existing helpdesk and use osTicket’s API or database import to load them. For Zendesk, community scripts exist. Historical ticket data (timestamps, agent assignments) can be preserved with direct database inserts, but this requires MySQL knowledge.