Instalar FreeScout Helpdesk no Linux: Guia Completo

O gerenciamento de tickets é uma das espinhas dorsais do suporte técnico moderno. Para empresas que buscam independência, controle total sobre os dados e personalização profunda, as soluções helpdesk linux self-hosted tornaram-se a escolha preferida em detrimento de SaaS genéricos. Neste tutorial técnico completo, guiamos você na instalação e configuração do FyneWorks Helpdesk (comumente associado ao ecossistema FreeScout no contexto de código aberto robusto) em um ambiente Linux moderno.

Embora o mercado ofereça alternativas como GLPI servidor próprio, Zammad, ou até mesmo a configuração de Chatwoot VPS para chat ao vivo, o FyneWorks/FreeScout destaca-se por ser um clone funcional do Help Scout, operando inteiramente via e-mail. Isso elimina a necessidade de interfaces web complexas para os usuários finais, reduzindo drasticamente a curva de aprendizado e a carga de processamento do servidor.

Este guia assume que você já possui acesso root ou sudo em um servidor Linux (preferencialmente Ubuntu 22.04 LTS ou Debian 12) e domínio configurado com registros DNS apontando para o IP do seu VPS. Vamos começar a configurar sua infraestrutura de suporte.

Pré-requisitos e Preparação do Ambiente

Antes de baixar qualquer código, é crucial preparar o sistema operacional. Um servidor de helpdesk exige estabilidade, segurança e um conjunto específico de bibliotecas para processar e-mails e renderizar interfaces web modernas. Vamos atualizar o índice de pacotes e instalar as ferramentas básicas de gerenciamento.

1. Atualize o sistema: Execute o comando abaixo para garantir que todos os pacotes existentes estejam na versão mais recente, corrigindo vulnerabilidades conhecidas.

sudo apt update && sudo apt upgrade -y

2. Instale ferramentas de segurança e rede: Precisamos de curl, wget, e um gerenciador de chaves GPG para baixar repositórios externos com segurança.

sudo apt install curl wget gnupg2 ca-certificates lsb-release -y

Este primeiro passo é fundamental para evitar erros de dependências futuras. Lembre-se: em um ambiente de produção, nunca ignore atualizações de segurança no kernel e nas bibliotecas base.

Instalação do Servidor Web Nginx e PHP

O FyneWorks Helpdesk é uma aplicação web escrita em PHP. Para que ela funcione, precisamos de um servidor web robusto e uma versão recente do PHP. O Nginx é preferido ao Apache pela sua eficiência no manejo de conexões concorrentes, especialmente importante para sistemas de tickets que recebem muitos e-mails simultaneamente.

Instalando o Nginx

O Nginx não está nos repositórios padrão do Ubuntu/Debian em algumas versões minimizadas. Vamos instalá-lo diretamente:

sudo apt install nginx -y

Inicie e habilite o serviço para garantir que ele suba automaticamente após reinicializações do servidor:

sudo systemctl enable --now nginx

Instalando o PHP e Extensões Essenciais

Aqui está o ponto crítico de muitos tutoriais mal escritos: a configuração do PHP. O Helpdesk exige extensões específicas para manipulação de imagens, criptografia, sockets e processamento de JSON. Vamos instalar o PHP 8.1 ou 8.2 (verifique a versão recomendada pela documentação oficial atual) com todas as dependências necessárias.

sudo apt install php8.2-fpm php8.2-common php8.2-mysql php8.2-curl php8.2-gd php8.2-intl php8.2-mbstring php8.2-xml php8.2-zip php8.2-bcmath php8.2-imap php8.2-redis -y

Nota Técnica: A extensão php8.2-imap é vital, pois o sistema opera lendo caixas de correio via protocolo IMAP/POP3. Sem ela, o helpdesk não conseguirá processar os tickets recebidos por e-mail.

Agora, precisamos ajustar o arquivo de configuração principal do PHP (php.ini) para aumentar os limites de upload e tempo de execução, comuns em sistemas que lidam com anexos de tickets.

sudo nano /etc/php/8.2/fpm/php.ini

Dentro do arquivo, encontre e modifique as seguintes linhas:

• memory_limit = 256M
• max_execution_time = 300
• upload_max_filesize = 10M
• post_max_size = 12M

Salve o arquivo (Ctrl+O, Enter) e saia (Ctrl+X). Reinicie o PHP-FPM para aplicar as mudanças:

sudo systemctl restart php8.2-fpm

Configuração do Banco de Dados MariaDB

Para armazenar os tickets, usuários e logs de comunicação, utilizaremos o MariaDB, um fork compatível e altamente performático do MySQL. Vamos instalar o servidor e garantir a segurança inicial.

sudo apt install mariadb-server -y

Execute o script de segurança para remover usuários anônimos, desativar login root remoto e remover banco de dados de teste:

sudo mysql_secure_installation

Siga o assistente, respondendo Y (Sim) para todas as perguntas. Quando solicitado, defina uma senha forte para o root do banco de dados.

Agora, vamos criar o banco de dados específico para o FyneWorks Helpdesk e um usuário dedicado com privilégios limitados a esse banco. Isso é uma prática de segurança essencial (princípio do menor privilégio).

sudo mariadb -u root -p

Dentro do prompt do MariaDB, execute os seguintes comandos SQL:

CREATE DATABASE fyneworks_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'fyneworks_user'@'localhost' IDENTIFIED BY 'SuaSenhaForteAqui';
GRANT ALL PRIVILEGES ON fyneworks_db.* TO 'fyneworks_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Substitua SuaSenhaForteAqui por uma senha complexa gerada por um gerenciador de senhas. Guarde essas credenciais, pois elas serão solicitadas durante a instalação da aplicação.

Instalação do Software FyneWorks Helpdesk

Agora que a infraestrutura está pronta (Web Server + PHP + Database), podemos baixar e configurar o código-fonte. Vamos utilizar o diretório /var/www/html como raiz da aplicação, mas em ambientes de produção robustos, recomenda-se criar um subdiretório dedicado.

1. Baixe o pacote: Acesse o repositório oficial ou a página de releases do projeto. Para este exemplo, utilizaremos o método via git para ter acesso às atualizações mais recentes.

cd /var/www/html
sudo git clone https://github.com/freescout-helpdesk/freescout.git .
# Nota: Em muitos casos, o projeto FyneWorks utiliza a base do FreeScout. Verifique sempre o repositório específico solicitado pelo fornecedor.

Importante: Se você estiver seguindo um tutorial de FyneWorks Helpdesk específico que fornece arquivos binários, substitua o comando git pelo download via wget e extração do tarball correspondente.

2. Ajuste de Permissões: O servidor web (www-data) precisa ter permissão de escrita em certas pastas para gerar logs, caches e processar anexos.

sudo chown -R www-data:www-data /var/www/html
sudo find /var/www/html -type d -exec chmod 755 {} \;
sudo find /var/www/html -type f -exec chmod 644 {} \;

Configuração do Nginx para o Helpdesk

O Nginx vem com uma configuração padrão que não serve para nossa aplicação. Precisamos criar um arquivo de servidor virtual (server block) que aponte para o diretório correto e processe as requisições PHP corretamente.

sudo nano /etc/nginx/sites-available/fyneworks-helpdesk

Cole a seguinte configuração, ajustando o server_name para o seu domínio:

server {
    listen 80;
    server_name helpdesk.seudominio.com.br;

    root /var/www/html/public;
    index index.php index.html;

    charset utf-8;
    gzip on;
    gzip_types text/css application/javascript text/javascript image/svg+xml application/json application/vnd.ms-fontobject application/x-font-ttf font/opentype;
    gzip_vary on;
    gzip_min_length 1000;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }

    # Segurança: Bloquear acesso a arquivos sensíveis
    location ~ /(config|storage|vendor)/ {
        deny all;
        return 404;
    }
}

Ative essa configuração criando um link simbólico para o diretório de sites habilitados e teste a sintaxe:

sudo ln -s /etc/nginx/sites-available/fyneworks-helpdesk /etc/nginx/sites-enabled/
sudo nginx -t

Se o teste retornar syntax is ok, recarregue o Nginx:

sudo systemctl reload nginx

Habilitação do SSL com Let's Encrypt

Nunca rode um sistema de suporte sem HTTPS. A criptografia protege as senhas e os dados dos clientes em trânsito. Vamos usar o Certbot para obter certificados gratuitos.

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d helpdesk.seudominio.com.br

O assistente do Certbot irá detectar sua configuração Nginx e perguntará se deseja redirecionar todo o tráfego HTTP para HTTPS. Responda 2 (Redirecionar). O certificado será instalado automaticamente e configurado para renovação.

Configuração do Firewall

Se você usa UFW (Uncomplicated Firewall), libere apenas as portas necessárias:

sudo ufw allow 'Nginx Full'
sudo ufw allow OpenSSH
sudo ufw enable

Instalação via Navegador e Configuração Inicial

Agora que o servidor está pronto, a instalação final ocorre via navegador web. Abra seu navegador e acesse https://helpdesk.seudominio.com.br.

1. Tela de Boas-vindas: Você verá uma tela solicitando a configuração do banco de dados.
2. Banco de Dados: Insira as credenciais criadas anteriormente:
   • Host: localhost
   • Database: fyneworks_db
   • User: fyneworks_user
   • Password: SuaSenhaForteAqui
3. Criação de Admin: Crie a conta do administrador inicial. Use um e-mail corporativo real, pois ele será o ponto central de gestão.
4. Verificação de Ambiente: O instalador verificará se todas as extensões PHP estão ativas. Se houver avisos em amarelo, volte ao passo de instalação do PHP e verifique se a extensão foi carregada corretamente.

Ao concluir, o sistema estará pronto para uso. Você será redirecionado para o painel administrativo (Dashboard).

Configuração de E-mail e Recebimento de Tickets

O coração do FyneWorks/FreeScout é a integração com e-mail. Para transformar mensagens em tickets, você precisa configurar uma conta de e-mail dedicada.

1. No painel admin, vá em Configurações > Contas de E-mail.
2. Clique em "Adicionar Conta".
3. Preencha os dados da sua caixa postal (IMAP/POP3). Se estiver usando um domínio próprio, crie o alias [email protected] no seu servidor de e-mail ou serviço de hospedagem.
4. Teste a Conexão: Clique em "Testar Configuração". Se aparecer uma mensagem verde de sucesso, o helpdesk consegue ler sua caixa postal.

Agora, configure as regras de roteamento para que novos e-mails sejam automaticamente convertidos em tickets na fila correspondente.

Manutenção e Segurança Pós-Instalação

Para garantir a longevidade do seu helpdesk linux, execute as seguintes tarefas rotineiras:

• Atualizações Semanais: Execute sudo apt update && sudo apt upgrade -y semanalmente.
• Cron Jobs: O sistema depende de processos em segundo plano (background jobs) para processar filas de e-mail. Verifique se o cron está ativo e configurado conforme a documentação oficial (geralmente requer um usuário específico executando scripts a cada minuto).
• Backups: Implemente backups diários do banco de dados e do diretório /var/www/html/storage. Scripts simples com mysqldump e rsync são suficientes para a maioria das VMs.

# Exemplo de backup diário via cron
0 2 * * * /usr/bin/mysqldump -u fyneworks_user -p'Senha' fyneworks_db | gzip > /backups/fyneworks_$(date +\%Y-\%m-\%d).sql.gz

Ao seguir este roteiro, você não apenas realiza a tarefa de instalar fyneworks helpdesk, mas estabelece uma base sólida para um sistema de suporte escalável, seguro e totalmente sob seu controle. Diferente de soluções SaaS onde seus dados estão em servidores terceiros, aqui você possui o suporte self-hosted completo, pronto para ser integrado com suas ferramentas internas via API.