--- og_image: "/images/guides/how-to-self-host-freescout-help-desk-2026.webp" title: "How to Self-Host FreeScout in 2026" description: "Self-host FreeScout in 2026 as a Help Scout or Zendesk alternative. Docker deployment, email mailbox setup, queue handling, backups, and upgrade tips." date: "2026-04-17" author: "OSSAlt Team" tags: ["freescout", "help-scout", "zendesk", "self-hosted", "help-desk"] featured_tool: "freescout" --- FreeScout is the closest open source equivalent to Help Scout's shared inbox experience. It's AGPL-3.0, pushed recently to `main`, and still sitting above 4.2K stars on GitHub. Teams migrating from Help Scout or Zendesk pick it because they want the same "email in a nice UI" feel without the per-agent bill. This guide focuses on a production FreeScout deployment: the parts that actually break in the first 90 days, not the happy-path install. ## Why self-host FreeScout FreeScout is a small, focused help desk built on PHP and Laravel. Teams reach for the self-hosted version for four reasons: - Unlimited agents and mailboxes without recurring seat fees. - Full control over where customer conversations live. - Freedom to install community modules (workflows, canned replies, ratings, Kanban). - Easy to run on a single modest VPS. It's not trying to be Zendesk. It's trying to be a faster, cheaper, self-hosted Help Scout, and it mostly succeeds. ## Requirements and mailbox prerequisites Before you start: - A Linux VPS (1–2 vCPU, 2–4 GB RAM is plenty for small teams). - A domain like `support.yourcompany.com` with DNS you control. - A dedicated support mailbox (`support@yourcompany.com`) on a provider you trust. - Correct SPF, DKIM, and DMARC records on the sending domain. If your email deliverability isn't clean before you start, FreeScout won't fix it, and replies may go to spam. ## Docker Compose stack The official FreeScout Docker image (maintained by the community) works well. A realistic stack: ```yaml services: freescout: image: tiredofit/freescout:latest env_file: .env.freescout volumes: - fs-data:/data - fs-logs:/var/log ports: - "8080:80" depends_on: - db restart: unless-stopped db: image: mariadb:11 environment: MARIADB_ROOT_PASSWORD: changeme MARIADB_DATABASE: freescout MARIADB_USER: freescout MARIADB_PASSWORD: changeme volumes: - db-data:/var/lib/mysql restart: unless-stopped volumes: fs-data: fs-logs: db-data: ``` Put Caddy or Traefik in front of it for TLS. Don't expose port 8080 publicly. ## SMTP and IMAP/forwarding setup notes FreeScout fetches mail from each mailbox and sends replies through SMTP. You have two viable ingest patterns: - **IMAP fetch**: FreeScout polls the mailbox on an interval (usually 1 minute). - **Forwarding**: your provider forwards every inbound message to a FreeScout-specific inbound address. Forwarding is faster and less fragile, but IMAP is simpler to configure. Start with IMAP if you're new to FreeScout. For outbound, use a real transactional provider (Postmark, SES, Mailgun, Resend) rather than your mailbox's SMTP. This keeps agent replies deliverable even at higher volumes. ## Queues, workflows, and attachments A few configuration points that matter in production: - **Cron and queue worker**: FreeScout needs its scheduled task to run every minute and its queue worker to stay alive. The Docker image handles this, but verify in `/var/log` after install. - **Workflows**: the Workflows module is how you automate routing, tagging, and auto-replies. Plan your first 3–5 workflows instead of creating dozens. - **Attachments**: by default they sit on disk. For teams with volume, mount that directory onto network storage or switch to an S3-compatible provider via a module. - **Signatures and templates**: build them early; rewriting signatures later is tedious. ## Backups and upgrades The non-negotiables: - Daily MariaDB/MySQL dumps pushed off-box (S3, B2, or another VPS). - Weekly snapshot of the attachments volume. - Test restore once, to a staging container, before you need it. - Pin FreeScout image tags; don't chase `latest` in production. Before major upgrades, back up, read the release notes, and take a staging pass. FreeScout's upgrades are generally smooth, but modules can lag behind core releases. Pair this with the more general [self-hosting backup guide](/guides/self-hosting-backup-guide-2026) for a broader baseline. ## Security hardening and common failure modes The mistakes that bite new FreeScout operators: - **No fail2ban or login rate limiting**: support admin logins are attractive targets. Put the admin path behind your VPN or IP allowlist if possible. - **Shared mailbox password in plain env files**: use a secrets manager or restricted permissions on `.env`. - **SPF/DKIM drift**: if you change email providers, re-check DNS or your replies will start hitting spam silently. - **Unbounded disk use**: attachments grow quietly. Monitor disk, and set a retention policy if you handle big files. - **Forgotten cron**: if the scheduler stops, new mail silently stops appearing. Health-check it. ## When to use FreeScout vs Chatwoot/Zammad FreeScout is the right pick if: - You're coming from Help Scout or a light Zendesk setup. - Your workflow is mostly email and you want minimal agent retraining. - You value low operational overhead. Choose differently if: - You need strong SLA and escalation features → [Zammad](/guides/best-open-source-alternatives-to-zendesk-2026). - You need live chat, WhatsApp, and social channels in the same inbox → Chatwoot. For the full comparison, see our [Help Scout alternatives roundup](/guides/best-open-source-alternatives-to-helpscout-2026). For broader Zendesk replacements, see the [Zendesk alternatives roundup](/guides/best-open-source-alternatives-to-zendesk-2026). ## Pre-launch decision checklist Before you migrate the team off Help Scout (or off shared Gmail), confirm each of these: - **DNS is clean.** SPF, DKIM, and DMARC validate green at mail-tester.org for the support sending domain. If they don't, fix DNS first; nothing else matters until replies land in the inbox. - **Ingest method is chosen and tested.** IMAP poll vs forwarding is a one-time decision. Pick one, send three test threads end-to-end, confirm they land as conversations within 60 seconds. - **Outbound provider is real.** Don't reply through a Gmail mailbox at scale; switch to Postmark/SES/Mailgun before the first agent touches the queue. - **Cron and queue worker are alive.** `docker exec` into the container and confirm the scheduler tick. If the worker dies silently, every customer reply queues up invisibly. - **Backups have been restored.** Restore yesterday's MariaDB dump into a throwaway container and load the UI. Untested backups are not backups. - **Admin login is gated.** Put `/users/login` behind your VPN, an IP allowlist, or at least Cloudflare Access. The admin path is the obvious target. - **Module versions are pinned.** Pin FreeScout core and every paid module to a specific version. Auto-pulled `latest` will eventually push a breaking core/module pair on a Friday afternoon. ## Common mistakes to avoid - **Connecting personal Gmail accounts as mailboxes.** OAuth tokens expire, ToS gets murky, and IMAP throttling will bite. Always use a dedicated `support@` mailbox you control at the provider level. - **Building 30 workflows on day one.** Start with the 3 you actually need (assign to me, mark spam, auto-reply out-of-hours). Add more only when you see the manual pattern repeat. - **Letting attachment storage grow on the app disk.** A few months of customer screenshots and PDFs will fill a small VPS. Mount external storage or switch to S3 before the volume gets uncomfortable. - **Skipping the staging container for upgrades.** FreeScout core upgrades are smooth; module upgrades sometimes are not. Run the upgrade against a staging copy with the same modules first. - **Reusing the support mailbox password across services.** That mailbox sees customer data, billing, and resets. Use a unique strong password and store it in a secrets manager, not `.env` on the host. FreeScout rewards teams who keep scope tight: one VPS, one or two mailboxes, a handful of workflows, and clean email DNS. Start there, then layer modules as you grow.