--- title: "Como instalar ResourceSpace com Docker no Debian" date: 2026-07-18 summary: "Guia completo para planejar, instalar, proteger, operar, atualizar e restaurar o ResourceSpace 11 com Docker Compose no Debian." tags: [pesquisa, resourcespace, docker, debian, mariadb, dam, self-hosting] flowerColor: "#72d6c9" --- # Como instalar ResourceSpace com Docker no Debian Este documento verifica e amplia as informações fornecidas sobre o ResourceSpace, com foco em uma instalação autohospedada no Debian por Docker Compose. Além da instalação, cobre dimensionamento, armazenamento, limites de upload, processamento de mídia, proxy reverso, fila offline, segurança, backup, restauração e atualização. ## Resumo executivo O ResourceSpace é um DAM — sistema de gestão de ativos digitais — baseado em PHP, Apache e banco compatível com MySQL. Na data desta pesquisa, o repositório Docker oficial entrega o **ResourceSpace 11.0**, lançado em 30 de junho de 2026. A imagem é construída sobre Ubuntu 24.04, mas pode ser executada normalmente por Docker Engine em um host Debian 12 ou 13. A instalação oficial realmente usa dois serviços: - `resourcespace`: Apache, PHP 8.3 e ferramentas de mídia; - `mariadb`: banco de dados. O Compose oficial persiste o `filestore`, o banco e o `config.php`. Entretanto, ele é um ponto de partida mínimo, não uma receita completa de produção. Ele: - usa `mariadb` sem fixar uma série de versão; - publica `80:80` em todas as interfaces; - não configura HTTPS nem proxy reverso; - não possui healthcheck do banco; - fixa uploads PHP em 100 MB; - não configura a execução frequente da fila de trabalhos offline; - usa volumes nomeados, menos óbvios para backup manual; - não limita ou rotaciona explicitamente logs no Compose. Para uma instalação doméstica ou pequena equipe, recomendo: - Debian 13 ou 12 atualizado; - 4 a 6 núcleos modernos; - 8 GB de RAM; - SSD para MariaDB e arquivos operacionais; - armazenamento grande e com backup para o filestore; - rclone/restic/Borg ou sua solução habitual para uma cópia externa; - proxy reverso HTTPS; - ResourceSpace acessível apenas pelo proxy ou por Tailscale; - fila offline habilitada para vídeo e tarefas demoradas. GPU não é requisito. O container oficial usa FFmpeg na CPU e não configura Intel Quick Sync, VA-API, NVIDIA NVENC nem AMD AMF. Aceleração de hardware exigiria uma imagem personalizada, dispositivos repassados ao container, um FFmpeg compatível e parâmetros próprios. ### Recomendação direta Comece com CPU, 8 GB de RAM e sem versões alternativas de vídeo além do necessário. Instale o repositório oficial, mas rode um arquivo `compose.production.yaml` próprio. Mantenha a porta do ResourceSpace vinculada a `127.0.0.1:8080`, expondo o serviço somente por proxy HTTPS ou túnel Tailscale/SSH. ## Metodologia e critérios Foram consultados o repositório Docker oficial do ResourceSpace, sua base oficial de conhecimento, a documentação oficial do Docker para Debian e a imagem oficial do MariaDB. O Compose, Dockerfile, cron e entrypoint atuais foram examinados diretamente. Afirmações sobre versões, dependências e comportamento do filestore vêm das fontes oficiais. Como o projeto não publica uma tabela oficial de CPU, RAM e capacidade mínima, os números de hardware e reserva de armazenamento são **estimativas de planejamento**, identificadas como tal. ## O que o container oficial contém atualmente O Dockerfile oficial atual parte de `ubuntu:24.04`, instala Apache, PHP 8.3, ImageMagick, FFmpeg, Ghostscript, Poppler, ExifTool, antiword, OpenCV, Python, cron e Postfix. Ele baixa o ResourceSpace 11.0 do repositório SVN de releases. Os limites incorporados ao PHP são: ```ini upload_max_filesize = 100M post_max_size = 100M max_execution_time = 300 memory_limit = 1G ``` A informação de limite de 100 MB fornecida inicialmente está correta. ### Uma discrepância importante A página geral de requisitos também relaciona Inkscape para ajudar na geração de previews vetoriais. O Dockerfile oficial examinado **não instala Inkscape**. Ele tampouco instala LibreOffice, necessário se você quiser previews completos de formatos do Microsoft Office. Isso não impede a instalação, mas significa que a tela **Administração → Sistema → Verificação da instalação** deve ser consultada depois do primeiro acesso. Instale ou adicione à imagem apenas as ferramentas correspondentes aos formatos realmente usados. ### O cron incluído não processa a fila offline O container inicia o serviço `cron`, e o arquivo oficial em `/etc/cron.daily/resourcespace` executa `cron_copy_hitcount.php`. Essa tarefa consolida diariamente as contagens usadas na ordenação por relevância. Ela **não executa** `offline_jobs.php`. Se você habilitar a fila offline para vídeos, geração de previews ou downloads demorados, precisará programar esse script separadamente. ## Requisitos de software ### Host recomendado - Debian 13 Trixie ou Debian 12 Bookworm; - arquitetura amd64 ou arm64; - Docker Engine do repositório oficial; - plugin Docker Compose; - Git; - proxy reverso, se o serviço for publicado; - DNS apontando para o servidor, quando houver acesso público. O Docker também atende Debian 11, mas para uma instalação nova é preferível usar uma versão com vida útil maior. ### Requisitos internos do ResourceSpace 11 Segundo a documentação oficial: - MariaDB 10.4 ou superior, ou MySQL 8.0 ou superior; - Apache 2.4 recomendado; - PHP 8.2, 8.3, 8.4 ou 8.5 para ResourceSpace 11; - extensões PHP de banco, cURL, DOM, GD, Intl, mbstring, XML, ZIP, LDAP, IMAP, JSON, APCu e CLI; - ImageMagick, FFmpeg, Ghostscript, ExifTool e Inkscape conforme os tipos de mídia. ## Dimensionamento de hardware Não existe uma tabela oficial de mínimos. As estimativas abaixo consideram um único servidor executando ResourceSpace, MariaDB e processamento de previews. | Perfil | CPU | RAM | Observação | |---|---:|---:|---| | Laboratório e poucos arquivos | 2 núcleos | 4 GB | Interface funciona; vídeos convertem lentamente | | Acervo misto pequeno/médio | 4–6 núcleos | 8 GB | Recomendação inicial equilibrada | | Muitos vídeos ou lotes 4K | 8+ núcleos | 16 GB+ | Conversão pode saturar CPU e I/O | | Catálogo quase sem conversão | 2 núcleos | 4 GB | Banco e interface são relativamente leves | ### CPU FFmpeg e ImageMagick podem usar vários núcleos. Mais núcleos reduzem tempo de ingestão em lote, mas também aumentam concorrência de I/O. Limite a quantidade de trabalhos offline simultâneos antes de aumentar o hardware. ### RAM O `memory_limit = 1G` do PHP é por processo, não uma reserva total do container. Vários uploads ou previews simultâneos podem ultrapassar 4 GB de RAM no conjunto. O host também precisa de memória para MariaDB, cache do sistema de arquivos e Docker. ### GPU Não é necessária. A imagem oficial não passa `/dev/dri` e não inclui configuração NVENC/VA-API. Primeiro meça a demora real da CPU. Personalizar GPU antes de existir gargalo comprovado adiciona complexidade e dificulta atualizações. ## Planejamento de armazenamento O ResourceSpace guarda arquivos físicos no filestore, não no banco. Cada recurso possui uma pasta ofuscada com: - original; - miniaturas e previews; - arquivos alternativos; - temporários relacionados a certas operações. O banco guarda metadados, usuários, permissões, coleções, referências e configuração estrutural. ### Estimativa de capacidade Para **1 TB de originais**, reserve inicialmente **1,3 a 2 TB** para o filestore. É uma faixa de planejamento, não requisito oficial. - fotos e PDFs normalmente acrescentam previews pequenos; - áudio pode acrescentar waveform e versões derivadas; - vídeo pode gerar proxies e alternativas comparáveis em tamanho ao original; - múltiplos formatos alternativos podem mais que duplicar o consumo. Além disso, backup não deve ficar no mesmo volume. Um acervo de 1 TB com 500 GB de derivados e uma cópia local de backup já demanda aproximadamente 3 TB, antes de retenção ou snapshots. ### Organização recomendada no Debian ```text /opt/resourcespace/ Compose, Dockerfile oficial e configuração /srv/resourcespace/mariadb/ Dados ativos do MariaDB, preferencialmente SSD /srv/resourcespace/filestore/ Originais, previews e alternativas /srv/resourcespace/backups/ Dumps temporários; copiar para outro destino ``` Se houver SSD pequeno e array grande: - MariaDB no SSD; - filestore no array/pool grande; - backups em outro dispositivo e também fora do servidor. O ResourceSpace permite separar originais de previews com `$originals_separate_storage`, mas não habilite isso inicialmente. A migração exige configuração e execução de ferramenta própria; só compensa quando houver uma política clara de camadas de armazenamento. ### Quota preventiva O `config.php` aceita limites para impedir que uploads esgotem o disco: ```php $disksize = 1800; // limite total aproximado em GB $disk_quota_limit_size_warning_noupload = 100; // bloqueia uploads com 100 GB livres ``` Adapte os valores à capacidade real. Um disco completamente cheio pode corromper banco, interromper conversões e dificultar a recuperação. ## Arquitetura recomendada ```text Internet ou Tailscale | v Proxy reverso HTTPS | v 127.0.0.1:8080 -> ResourceSpace/Apache | v rede interna | v MariaDB Persistência: - /srv/resourcespace/filestore - /srv/resourcespace/mariadb - /opt/resourcespace/config.php ``` O MariaDB não deve publicar a porta 3306 no host. Só o ResourceSpace precisa alcançá-lo pela rede privada do Compose. ## Instalação passo a passo no Debian ### 1. Preparar o sistema ```bash sudo apt update sudo apt full-upgrade -y sudo apt install -y ca-certificates curl git openssl sudo reboot ``` O reboot só é necessário se kernel ou componentes fundamentais tiverem sido atualizados. ### 2. Instalar Docker Engine e Compose Remova pacotes conflitantes apenas se estiverem instalados: ```bash sudo apt remove -y docker.io docker-compose docker-doc podman-docker containerd runc ``` Adicione o repositório oficial: ```bash sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/debian/gpg \ -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null <> /var/log/resourcespace-offline-jobs.log 2>&1 ``` Comece com dois trabalhos concorrentes. Se vídeos deixarem o sistema lento, reduza para um. Se houver CPU e disco sobrando, aumente gradualmente observando `docker stats`, load average, temperatura e latência do armazenamento. O cron diário de `cron_copy_hitcount.php` já está presente na imagem oficial atual. ## Processamento de mídia e formatos ### Imagens ImageMagick e GD geram miniaturas e previews. Arquivos enormes ou formatos incomuns podem consumir muita memória. ### Vídeo e áudio FFmpeg gera previews e pode criar arquivos alternativos. A documentação recomenda a fila offline para não prender o upload enquanto a conversão ocorre. Não crie automaticamente três ou quatro qualidades sem necessidade. Para um DAM pequeno, um proxy H.264 de tamanho moderado costuma bastar para visualização, preservando o original para download. ### PDF Ghostscript e Poppler auxiliam na leitura e geração de previews. PDFs complexos devem ser testados depois da instalação. ### Microsoft Office O Dockerfile oficial não inclui LibreOffice. Se previews de DOCX, XLSX e PPTX forem importantes, será necessário criar uma imagem derivada ou acrescentar a instalação ao Dockerfile, aumentando tamanho e superfície de manutenção. ### Vetores Inkscape aparece nos requisitos gerais, mas não no Dockerfile oficial atual. Para SVG e formatos vetoriais, confirme o resultado na verificação da instalação e adicione Inkscape à imagem somente se necessário. ## Backups corretos Um backup recuperável precisa de três partes inseparáveis: 1. dump consistente do MariaDB; 2. cópia completa do filestore; 3. `config.php`, especialmente `$scramble_key` e `$api_scramble_key`. Também guarde `db.env`, `compose.production.yaml`, `php-upload.ini` e configuração do proxy em um cofre protegido. ### Backup manual com breve indisponibilidade ```bash cd /opt/resourcespace STAMP=$(date +%Y%m%d-%H%M%S) DEST="/srv/resourcespace/backups/$STAMP" sudo mkdir -p "$DEST" sudo docker compose -f compose.production.yaml stop resourcespace sudo docker compose -f compose.production.yaml exec -T mariadb \ sh -c 'mariadb-dump -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' \ | gzip | sudo tee "$DEST/resourcespace.sql.gz" >/dev/null sudo tar -C /srv/resourcespace -czf "$DEST/filestore.tar.gz" filestore sudo cp /opt/resourcespace/config.php "$DEST/config.php" sudo cp /opt/resourcespace/compose.production.yaml "$DEST/compose.production.yaml" sudo cp /opt/resourcespace/php-upload.ini "$DEST/php-upload.ini" sudo docker compose -f compose.production.yaml start resourcespace sudo sha256sum "$DEST"/* | sudo tee "$DEST/SHA256SUMS" ``` Parar somente a aplicação evita alterações enquanto banco e filestore são copiados. Para filestores grandes, use snapshots de ZFS/Btrfs/LVM ou `rsync` incremental em vez de criar um `.tar.gz` integral diariamente. ### Política recomendada - dump diário do banco; - snapshot ou backup incremental diário do filestore; - retenção diária, semanal e mensal; - ao menos uma cópia fora do servidor; - criptografia do backup externo; - teste de restauração trimestral. Siga a regra 3-2-1: três cópias, dois tipos de mídia, uma fora do local. ### Restauração resumida 1. instale a mesma versão do ResourceSpace e uma série compatível do MariaDB; 2. restaure `config.php` e o filestore; 3. importe o dump no banco vazio; 4. confira permissões do filestore; 5. suba a aplicação; 6. execute a verificação da instalação; 7. teste login, busca, download do original e geração de preview. Não considere o backup válido até realizar uma restauração de teste. ## Atualizações seguras Não use Watchtower para atualizar automaticamente ResourceSpace ou MariaDB. Mudanças de aplicação e banco exigem backup, leitura das notas e janela de manutenção. Procedimento recomendado: ```bash cd /opt/resourcespace # 1. Faça e valide o backup antes. git status --short git fetch --all --prune git log --oneline HEAD..origin/main # 2. Atualize apenas se não houver alterações inesperadas. git pull --ff-only # 3. Recrie e suba. sudo docker compose -f compose.production.yaml build --pull sudo docker compose -f compose.production.yaml up -d # 4. Verifique. sudo docker compose -f compose.production.yaml ps sudo docker compose -f compose.production.yaml logs --tail=200 ``` Antes de atualizar entre versões principais do ResourceSpace, leia as notas de versão e confirme a matriz de PHP. Antes de mudar a série do MariaDB, consulte as instruções de upgrade e valide restauração do dump. O arquivo personalizado possui nome diferente dos arquivos oficiais, portanto `git pull` não deve sobrescrevê-lo. Mesmo assim, `git status` deve estar limpo ou conter apenas os arquivos locais esperados. ## Segurança operacional ### Exposição de rede - não publique MariaDB; - não use `0.0.0.0:8080` sem necessidade; - use HTTPS; - restrinja o painel administrativo por VPN/Tailscale se possível; - lembre que portas publicadas pelo Docker podem contornar regras simples do UFW; - aplique regras persistentes na cadeia `DOCKER-USER` quando depender de firewall local. ### Credenciais - senhas diferentes para root do MariaDB, usuário da aplicação e administrador; - arquivos `db.env` e `config.php` com permissões restritas; - nenhuma credencial em Git, documentação compartilhada ou histórico de shell; - backup criptografado, porque o `config.php` contém segredos. ### Aplicação - desative contas anônimas se não forem necessárias; - use grupos com menor privilégio; - desative a API remota se não for usada: `$enable_remote_apis = false;`; - mantenha plugins no mínimo; - revise formatos de upload permitidos; - acompanhe a tela de verificação e logs após atualizações. ### Sistema e Docker - atualize o Debian regularmente; - monitore espaço, inodes e SMART dos discos; - limite crescimento de logs; - não monte `/var/run/docker.sock` em containers; - não adicione usuários comuns ao grupo `docker`; - proteja SSH com chaves e desative login root remoto quando possível. ## Monitoramento e diagnóstico Comandos úteis: ```bash sudo docker compose -f /opt/resourcespace/compose.production.yaml ps sudo docker compose -f /opt/resourcespace/compose.production.yaml logs -f --tail=100 sudo docker stats df -h /srv/resourcespace df -i /srv/resourcespace du -sh /srv/resourcespace/filestore /srv/resourcespace/mariadb ``` Teste após a instalação: 1. upload de JPEG e geração de miniatura; 2. upload de PDF e visualização; 3. upload de vídeo pequeno e conclusão da fila; 4. download do original; 5. busca por metadados; 6. criação de usuário sem privilégios administrativos; 7. upload maior que 100 MB; 8. reinício completo do host; 9. restauração em ambiente separado. ### Problemas comuns | Sintoma | Causa provável | Verificação | |---|---|---| | Setup não grava configuração | Permissão do `config.php` | proprietário 33:33 e modo 600 | | ResourceSpace não conecta ao banco | host usado como `localhost` | usar `mariadb` | | Upload para em 100 MB | override PHP não carregou | `php -i` dentro do container | | Proxy retorna 413 | limite do proxy menor | aumentar `client_max_body_size` | | Upload expira | timeout do PHP/proxy | conferir ambos | | Preview de vídeo nunca aparece | fila offline sem cron | executar `offline_jobs.php` manualmente | | Filestore não gravável | UID/GID do bind mount | `ls -ln` no host e teste da instalação | | Banco reinicia sem parar | permissão ou disco cheio | logs do serviço MariaDB | | DOCX sem preview | LibreOffice ausente | decidir se vale imagem personalizada | Para confirmar o PHP efetivo: ```bash sudo docker compose -f /opt/resourcespace/compose.production.yaml exec \ resourcespace php -i | grep -E \ 'upload_max_filesize|post_max_size|max_execution_time|max_input_time|memory_limit' ``` ## Avaliação das informações fornecidas | Informação inicial | Avaliação | |---|---| | Dois containers, ResourceSpace e MariaDB | Correta | | Banco e filestore persistentes | Correta; `config.php` também é bind mount | | Sem requisitos oficiais de CPU/RAM | Correta | | 4–6 núcleos e 8 GB para uso misto | Estimativa sensata | | GPU dispensável | Correta para a imagem oficial | | 1 TB de originais → 1,3–2 TB | Boa reserva inicial, não garantia | | Upload oficial limitado a 100 MB | Correta no Dockerfile atual | | FFmpeg, ImageMagick, Ghostscript, ExifTool e Poppler | Presentes no Dockerfile atual | | Inkscape incluído no container | Incorreta: consta nos requisitos, mas não no Dockerfile atual | | Fila offline disponível | Correta, mas precisa ser habilitada e agendada | | Compose oficial pronto para produção | Incompleta: faltam TLS, healthcheck, pinagem e política operacional | ## Recomendações práticas 1. Comece no Debian 13 ou 12 com 4–6 núcleos e 8 GB. 2. Use o repositório oficial, mas rode o Compose de produção desta pesquisa. 3. Mantenha ResourceSpace em localhost atrás de HTTPS ou Tailscale. 4. Use SSD para MariaDB e armazenamento protegido para o filestore. 5. Limite uploads no PHP e no proxy com o mesmo valor. 6. Habilite fila offline e comece com no máximo dois trabalhos. 7. Não personalize GPU, LibreOffice ou Inkscape até confirmar a necessidade. 8. Faça backup de banco, filestore e `config.php` como um conjunto. 9. Fixe séries de versão e atualize manualmente após backup. 10. Faça a verificação interna e uma restauração de teste antes de importar o acervo completo. ## Conclusão ResourceSpace é uma escolha viável para organizar fotos, vídeos, áudio e documentos em um servidor Debian. A estimativa de 4–6 núcleos, 8 GB de RAM e CPU para conversão é um ponto inicial realista. O componente decisivo será o armazenamento: filestore e backup crescerão muito mais que o banco. A instalação oficial funciona, mas deve ser endurecida antes de receber arquivos importantes. O Compose proposto resolve os principais pontos sem criar arquitetura excessiva: MariaDB privado e com série fixa, healthcheck, bind mounts previsíveis, porta local, logs limitados e override de upload. O maior risco não é falta de GPU; é operar sem backup restaurável, fila offline, limite coerente no proxy e espaço livre monitorado. Instale primeiro com um conjunto pequeno de arquivos, valide todos os formatos usados e só depois migre o acervo. ## Fontes consultadas - [ResourceSpace — instalação oficial via Docker](https://www.resourcespace.com/knowledge-base/systemadmin/install_docker) - [ResourceSpace — repositório Docker oficial](https://github.com/resourcespace/docker) - [ResourceSpace Docker — Compose oficial](https://github.com/resourcespace/docker/blob/main/docker-compose.yaml) - [ResourceSpace Docker — Dockerfile oficial](https://github.com/resourcespace/docker/blob/main/Dockerfile) - [ResourceSpace Docker — tarefa cron incluída](https://github.com/resourcespace/docker/blob/main/cronjob) - [ResourceSpace Docker — entrypoint oficial](https://github.com/resourcespace/docker/blob/main/entrypoint.sh) - [ResourceSpace — requisitos gerais](https://www.resourcespace.com/knowledge-base/systemadmin/general_requirements) - [ResourceSpace — visão geral da instalação](https://www.resourcespace.com/knowledge-base/systemadmin/install_overview) - [ResourceSpace — arquivo de configuração](https://www.resourcespace.com/knowledge-base/systemadmin/config-file) - [ResourceSpace — funcionamento do filestore](https://www.resourcespace.com/knowledge-base/systemadmin/filestore) - [ResourceSpace — fila de trabalhos offline](https://www.resourcespace.com/knowledge-base/systemadmin/offline_job_queues) - [ResourceSpace — vídeos alternativos automáticos](https://www.resourcespace.com/knowledge-base/systemadmin/alternative-video-files) - [ResourceSpace — backup](https://www.resourcespace.com/knowledge-base/systemadmin/backup) - [ResourceSpace — restauração](https://www.resourcespace.com/knowledge-base/systemadmin/restore) - [ResourceSpace — checksums](https://www.resourcespace.com/knowledge-base/systemadmin/checksums) - [ResourceSpace — formatos suportados](https://www.resourcespace.com/knowledge-base/resourceadmin/supported_file_formats) - [Docker — instalar Docker Engine no Debian](https://docs.docker.com/engine/install/debian/) - [Docker — pós-instalação no Linux e privilégio do grupo docker](https://docs.docker.com/engine/install/linux-postinstall/) - [MariaDB — imagem Docker oficial](https://hub.docker.com/_/mariadb) --- ### Nota sobre atualidade Pesquisa concluída em **18 de julho de 2026**. O repositório oficial apontava para ResourceSpace 11.0 e PHP 8.3; versões, caminhos internos, tags do MariaDB e requisitos podem mudar. Antes da instalação ou atualização, confira o Dockerfile, o Compose, a matriz de PHP e as notas oficiais atuais.