nfrastack/container-freescout

About

This repository will build a container image for running FreeScout - an open source Help Scout / Zendesk alternative for shared inboxes, helpdesk, and ticketing.

Maintainer

• Nfrastack

Table of Contents

• About
• Maintainer
• Table of Contents
• Installation
  • Prebuilt Images
  • Quick Start
  • Persistent Storage
• Configuration
  • Environment Variables
    • Base Images used
    • Core Configuration
    • Database
    • Application
    • Setting Arbitrary FreeScout Keys
    • Scheduler
  • Networking
• Upgrading from 1.x
• Maintenance
  • Shell Access
• Support & Maintenance
• License
• References

Installation

Prebuilt Images

Builds are available on the Github Container Registry and Docker Hub:

ghcr.io/nfrastack/container-freescout:(image_tag)
docker.io/nfrastack/freescout:(image_tag)

Image tag syntax is:

<image>:<optional tag>-<optional phpversion>

Example:

docker.io/nfrastack/freescout:latest or ghcr.io/nfrastack/container-freescout:2.0-php84

• latest will be the most recent commit on the latest PHP version
• An optional tag may exist that matches the CHANGELOG - these are the safest

PHP version	Tag
8.5.x	:<imageversion>-php8.5
8.4.x	:<imageversion>-php8.4
	:latest
8.3.x	:<imageversion>-php8.3

Have a look at the container registries and see what tags are available.

Multi-Architecture Support

Images are built for amd64 by default, with optional support for arm64 and other architectures.

Quick Start

• The quickest way to get started is using docker-compose. See examples/compose.yml for a working stack you can tailor to your environment.
• Map persistent storage for access to configuration and data files for backup.
• Set environment variables to control container behavior.

The first boot can take 2-5 minutes depending on your CPU as the schema is created and assets are warmed.

Persistent Storage

The following directories should be mapped for persistent storage. The /data mount is recommended - it covers config, sessions, cache, modules, and the version marker in one place. Mounting /www/html instead is supported when you want the FreeScout source tree exposed for inspection or self-update.

Directory	Description
/logs	Nginx and PHP log files
/www/html	(Optional) Expose the FreeScout source tree to the host
OR
/data	Persistent state - sessions, cache, uploads, Modules/, configuration

Configuration

Environment Variables

This image relies on a customized base image in order to work. Be sure to view the following repositories to understand all the customizable options:

Base Images used

Image	Description
OS Base	Base image
Nginx	Nginx webserver
Nginx PHP-FPM	PHP-FPM interpreter
Laravel	Laravel runtime

Below is the complete list of available options that can be used to customize your installation.

• Variables showing an 'x' under the Advanced column can only be set if the containers advanced functionality is enabled.

Core Configuration

Parameter	Description	Default	_FILE
SETUP_TYPE	AUTO writes config, runs migrations, creates the bootstrap admin. MANUAL does nothing	AUTO
ADMIN_EMAIL	Email of the bootstrap admin user (created on a fresh DB only)	admin@example.com	x
ADMIN_FIRST_NAME	First name of the bootstrap admin	Admin	x
ADMIN_LAST_NAME	Last name of the bootstrap admin	User	x
ADMIN_PASS	Password of the bootstrap admin	freescout	x
ENABLE_AUTO_UPDATE	Auto-upgrade FreeScout source on container restart when image version differs from ${DATA_PATH}/.freescout-version	TRUE
DATA_PATH	Base persistent-data path (sessions, cache, modules, version marker live under here)	/data/
MODULES_PATH	Persistent storage for FreeScout Modules/ directory	${DATA_PATH}/Modules
ENABLE_FREESCOUT_SCHEDULER	Run php artisan schedule:run once per minute. Required for mail fetch / digest / queue	TRUE

Database

Parameter	Description	Default	_FILE
DB_TYPE	Database driver: mysql, mariadb, or pgsql / postgres	mysql
DB_HOST	Hostname or container name of the database server		x
DB_PORT	Database port	3306	x
DB_NAME	Database name (written to .env as DB_DATABASE)		x
DB_USER	Database username (written to .env as DB_USERNAME)		x
DB_PASS	Database password (written to .env as DB_PASSWORD)		x
DB_SSL	Enable SSL connectivity (TRUE / FALSE) for MySQL/MariaDB	FALSE

Application

Parameter	Description	Default	Alias	_FILE
APP_URL	Full external URL of the site (e.g. https://freescout.example.com). Required.		SITE_URL
SITE_URL	Legacy alias for APP_URL

Setting FreeScout configuration

FreeScout ships ~80 configuration keys (look inside the running container at /www/html/.env.example for a sample, or read the upstream wiki).

Any environment variable starting with FREESCOUT_ is stripped of that prefix and written into the runtime config:

environment:
  - FREESCOUT_APP_PROXY=http://proxy.local:3128
  - FREESCOUT_APP_TRUSTED_PROXIES=10.0.0.0/8
  - FREESCOUT_APP_X_FRAME_OPTIONS=DENY
  - FREESCOUT_APP_LOCALE=en
  - FREESCOUT_APP_TIMEZONE=America/Vancouver
  - FREESCOUT_MAIL_DRIVER=smtp
  - FREESCOUT_MAIL_HOST=postfix-relay
  - FREESCOUT_MAIL_PORT=25
  - FREESCOUT_DB_PGSQL_SSL_MODE=require

becomes the following lines in (/data/config/config | /www/html/.env:

APP_PROXY=http://proxy.local:3128
APP_TRUSTED_PROXIES=10.0.0.0/8
APP_X_FRAME_OPTIONS=DENY
APP_LOCALE=en
APP_TIMEZONE=America/Vancouver
MAIL_DRIVER=smtp
MAIL_HOST=postfix-relay
MAIL_PORT=25
DB_PGSQL_SSL_MODE=require

Three special values delete the matching .env line: FREESCOUT_FOO=unset, FREESCOUT_FOO=null, FREESCOUT_FOO=

Docker secrets: any FREESCOUT_<KEY>_FILE=/run/secrets/x is resolved into FREESCOUT_<KEY>=<contents> before passthrough.

Scheduler

FreeScout requires php artisan schedule:run to fire once per minute for mail fetching, queue dispatching, and report digests. This is an alternative to the in place cron service. Most people will not want this enabled. It is here for edge cases.

Parameter	Description	Default
ENABLE_FREESCOUT_SCHEDULER	Toggle the in-container scheduler.	FALSE

Networking

The following ports are exposed.

Port	Description
80	HTTP

---

Maintenance

Shell Access

For debugging and maintenance, bash and sh are available in the container. An artisan shell function is preinstalled and runs as the nginx user against /www/html/artisan.

docker exec -it freescout-app bash
artisan tinker

Support & Maintenance

• For community help, tips, and discussions, visit the Discussions board.
• For personalized support or a support agreement, see Nfrastack Support.
• To report bugs, submit a Bug Report. Usage questions will be closed as not-a-bug.
• Feature requests are welcome but not guaranteed.
• Updates are best-effort, with priority given to active production use and support agreements.

License

This project is licensed under the MIT License - see the LICENSE file for details.

References

• https://freescout.net/
• https://github.com/freescout-helpdesk/freescout/wiki
• https://github.com/freescout-helpdesk/freescout/wiki/Configuration