Como adicionar fontes personalizadas ao servidor de documentos ONLYOFFICE

Para disponibilizar uma fonte personalizada no ONLYOFFICE Docs, instale os arquivos da fonte na máquina ou no contêiner que executa o Servidor de Documentos, regenere a lista de fontes do servidor e verifique o resultado em um editor e em um documento exportado. O procedimento exato para persistir os arquivos depende se o seu servidor está instalado diretamente no Linux ou se está sendo executado em um contêiner Docker.

Uma alteração bem-sucedida significa que a fonte aparece com seu nome de família no seletor de fontes do editor e é exibida conforme o esperado em um documento de teste. Ver um nome no menu é uma primeira verificação útil, mas não garante que todos os estilos, idiomas ou caminhos de exportação funcionem. Verifique o texto normal e em negrito, quaisquer conjuntos de caracteres necessários e uma pré-visualização em PDF ou impressão antes de usar a fonte em documentos de produção.

O que muda quando você instala uma fonte?

O ONLYOFFICE Docs utiliza fontes disponíveis no servidor de documentos e gera metadados de fontes para seus editores. Os guias de instalação do fornecedor listam as famílias TrueType e OpenType, incluindo .ttf, .otf, .ttce formatos relacionados, bem como formatos WOFF. Os tipos de arquivo suportados não garantem que todos os arquivos de fonte ou recursos de fonte se comportarão da mesma forma; teste a fonte e o documento específicos que você pretende usar.

A instalação da fonte no servidor permite que os editores conectados usem a fonte por meio do Servidor de Documentos. Ela não instala a fonte em todos os computadores dos usuários nem em outros servidores de processamento de documentos. Se um arquivo baixado ou aberto separadamente for visualizado em um software que não possui a fonte, esse software poderá substituí-la por outra. A ONLYOFFICE também observa que os documentos podem ser exibidos com uma fonte substituta semelhante quando o servidor não possui a fonte usada no documento, o que pode alterar as quebras de linha ou o layout da página.

Utilize arquivos de fontes que você tenha autorização para implantar em um servidor. Mantenha os arquivos e seus termos de licença junto com seus registros de implantação, especialmente se a fonte tiver restrições de uso em servidor, redistribuição ou incorporação em documentos.

Escolha o método de instalação correto

• Instalação do pacote Linux: copie os arquivos de fonte para o diretório de fontes do sistema no servidor de documentos e, em seguida, execute o script de geração de fontes do ONLYOFFICE. Isso é apropriado quando você gerencia o host diretamente.
• Contêiner Docker: monte um diretório persistente do host no diretório de fontes do contêiner ou copie as fontes para um contêiner em execução para um teste de curta duração. Regenere os metadados da fonte dentro do contêiner. Uma montagem de diretório persiste mesmo após a recriação do contêiner; uma cópia única para o contêiner geralmente não persiste.
• Implantação gerenciada ou integrada: se outra plataforma ou ferramenta de instalação gerenciar o contêiner do Servidor de Documentos, aplique a montagem persistente por meio da configuração dessa implantação. A edição de um contêiner em execução isoladamente pode resultar na perda do conteúdo durante uma atualização ou substituição.

Os guias de fontes atualmente publicados pela ONLYOFFICE mostram o mesmo fluxo principal para a Community Edition no Linux e no Docker, e publicam um guia separado para Linux para a Enterprise Edition. Os caminhos, permissões e orquestração de contêineres podem variar de acordo com a sua versão e método de instalação; portanto, use a configuração existente da sua implantação em vez de substituí-la por um exemplo de outro ambiente.

Adicionar fontes em uma instalação do Linux

1. Prepare e instale os arquivos de fonte.

Obtenha os arquivos de família de fontes necessários, incluindo as variantes em negrito e itálico, se a família as fornecer. Mantenha uma família de fontes organizada em um diretório com nome claro. Por exemplo, um administrador pode colocar uma família de fontes em `/usr/local/bin` /usr/share/fonts/, o local do sistema usado nas instruções do ONLYOFFICE para Linux:

sudo mkdir -p /usr/share/fonts/custom/brand-sans
sudo cp BrandSans-*.ttf /usr/share/fonts/custom/brand-sans/

Substitua os nomes de arquivo de exemplo pelos arquivos que você realmente possui. Evite renomear arquivos de fonte como forma de alterar o nome da família; os editores usam metadados armazenados em cada arquivo de fonte. Certifique-se de que os processos do Servidor de Documentos possam ler os arquivos. Se você gerencia fontes por meio de um sistema de gerenciamento de pacotes ou configuração, use esse processo para que os arquivos permaneçam presentes após a manutenção.

2. Regenerar a lista de fontes do ONLYOFFICE

Execute o script de geração de fontes do fornecedor após instalar os arquivos:

sudo /usr/bin/documentserver-generate-allfonts.sh

Aguarde a conclusão do script e revise a saída em busca de erros. Esta etapa atualiza os dados de fonte usados ​​pelo Servidor de Documentos; simplesmente copiar um arquivo de fonte para o host pode não fazer com que ele apareça em um editor já em execução. Não remova as fontes existentes do servidor como parte deste procedimento. O fornecedor alerta que a exclusão de fontes do sistema pode afetar o layout e a exibição do documento.

Adicionar fontes a uma implantação do Docker

1. Torne o diretório de fontes persistente.

Para uma implantação gerenciada com Docker Compose, adicione uma montagem de volume (bind mount) ao serviço Document Server existente. Crie um diretório no host para os arquivos e, em seguida, mapeie-o para o diretório de fontes personalizadas do contêiner. A imagem Docker da ONLYOFFICE declara o diretório /usr/share/fonts/truetype/customcomo um volume, e suas instruções de fontes Docker também permitem copiar fontes para esse diretório /usr/share/fonts/.

services:
  onlyoffice-documentserver:
    image: onlyoffice/documentserver:<your-pinned-version>
    volumes:
      - /srv/onlyoffice/fonts:/usr/share/fonts/truetype/custom

Este é um trecho para mesclar ao seu arquivo Compose atual, não uma configuração de substituição completa. Mantenha sua versão de imagem, redes, variáveis ​​de ambiente, volumes de dados, segredos e nome do serviço existentes. Prepare os arquivos de fonte no host /srv/onlyoffice/fontse certifique-se de que o contêiner possa lê-los.

Aplicar um arquivo Compose modificado pode recriar o contêiner do Document Server e interromper as sessões de edição ativas. Verifique seu procedimento de implantação, faça um backup da configuração do Compose e agende a alteração adequadamente. Se o contêiner for gerenciado por um dispositivo ou integração, use o método de configuração compatível em vez de editar um arquivo Compose gerado.

2. Recrie ou reinicie e, em seguida, gere os metadados da fonte.

Aplique a montagem usando o fluxo de trabalho Compose normal para sua implantação. Em seguida, execute o script de geração de fontes dentro do contêiner do Document Server. Para um contêiner chamado onlyoffice-documentserver, o comando é:

docker exec onlyoffice-documentserver   /usr/bin/documentserver-generate-allfonts.sh

Use o nome ou ID do contêiner exibido por docker ps. Se você quiser apenas verificar uma fonte antes de tornar a configuração permanente, o fornecedor documenta como copiar arquivos de fonte para um contêiner em execução com docker cp, seguido da execução do mesmo script dentro dele. Considere isso como um teste: os arquivos copiados para um contêiner podem desaparecer quando o contêiner for substituído.

Verifique a fonte em um editor e na saída.

1. Abra um documento em um editor conectado a este Servidor de Documentos e abra o seletor de fontes. Procure pelo nome da família da fonte, conforme registrado em seus metadados.
2. Crie um pequeno documento de teste com texto normal, texto em negrito e caracteres dos alfabetos dos idiomas que você precisa. Confirme se a espessura correta está selecionada, em vez de um estilo sintético ou substituto.
3. Salve, reabra e exporte ou visualize a impressão do documento de teste. Compare as quebras de linha, a contagem de páginas, o espaçamento e a cobertura de glifos com o resultado esperado.
4. Repita a verificação no editor de documentos ou aplicativo que seus usuários realmente utilizam. A disponibilidade de uma fonte no servidor não garante que ela esteja presente em um aplicativo local independente ou em outro servidor.

Em instalações mais antigas, os metadados de fontes armazenados em cache no navegador podem causar atrasos na exibição das informações para o usuário. Os guias publicados pela ONLYOFFICE recomendam que, para a versão 8.1.3 ou anterior, seja necessário limpar o cache do navegador e reabrir a página após adicionar as fontes; para versões posteriores, essa etapa não é necessária. Primeiro, verifique os arquivos do servidor e os metadados gerados e, em seguida, utilize essa recomendação de limpeza de cache somente se ela corresponder à sua versão.

Se a fonte estiver faltando ou o layout mudar

• A fonte não está disponível no seletor: confirme se o arquivo está no diretório de fontes do servidor de documentos ou dentro do contêiner correto, se é legível e se possui um tipo de arquivo compatível. Execute o script de geração de fontes novamente e leia a saída. No Docker, verifique a montagem de dentro do contêiner; apenas o caminho do host não comprova que o volume está associado ao serviço ativo.
• O nome da família parece diferente: verifique os metadados da família incorporados na fonte. Um nome de arquivo como esse BrandSans-Bold.ttfpode estar instalado corretamente, enquanto o menu mostra o nome da família definido dentro da fonte.
• A fonte aparece, mas o texto está incorreto: verifique se a fonte inclui os caracteres necessários e os arquivos de estilo corretos. Uma fonte pode aparecer no seletor, mas não possuir um glifo ou peso usado no documento.
• Os documentos são redimensionados após a alteração: compare a família e o estilo exatos da fonte usados ​​antes e depois. Se a fonte original estiver faltando em outra máquina ou serviço de exportação, uma fonte substituta pode alterar o layout. Instale a fonte licenciada em todos os locais onde a renderização ocorre ou use uma alternativa segura para documentos e revise as páginas novamente.
• A fonte desaparece após uma atualização: verifique se a instalação foi feita apenas em um contêiner descartável. Mova os arquivos para um diretório de host persistente e anexe-o por meio da configuração de implantação antes de recriar o serviço.

Adicionar fontes personalizadas é mais útil quando a mesma família de fontes é necessária em documentos compartilhados e exportações controladas. No entanto, essa prática tem limitações: a instalação no servidor não concede direitos de uso da fonte, não adiciona glifos ausentes a uma fonte e não garante renderização idêntica em pixels em softwares que utilizam um conjunto de fontes diferente. Mantenha o diretório de fontes personalizadas sob controle de versão ou gerenciamento de configuração, documente a versão do Servidor de Documentos e execute novamente as verificações após as atualizações.

Referências oficiais

• ONLYOFFICE Docs Community Edition: Adicionando fontes no Linux
• ONLYOFFICE Docs Community Edition: Adicionando fontes no Docker
• ONLYOFFICE Docs Enterprise Edition: Adicionando fontes no Linux
• Repositório ONLYOFFICE Docker-DocumentServer