Moon Flower Society > Como instalar ResourceSpace com Docker no Debian
Guia completo para planejar, instalar, proteger, operar, atualizar e restaurar o ResourceSpace 11 com Docker Compose no Debian.
Posted July 18, 2026. Markdown. Tags: pesquisa, resourcespace, docker, debian, mariadb, dam, self-hosting.
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.
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:
mariadb sem fixar uma série de versão;80:80 em todas as interfaces;Para uma instalação doméstica ou pequena equipe, recomendo:
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.
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.
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 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:
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.
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 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.
O Docker também atende Debian 11, mas para uma instalação nova é preferível usar uma versão com vida útil maior.
Segundo a documentação oficial:
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 |
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.
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.
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.
O ResourceSpace guarda arquivos físicos no filestore, não no banco. Cada recurso possui uma pasta ofuscada com:
O banco guarda metadados, usuários, permissões, coleções, referências e configuração estrutural.
Para 1 TB de originais, reserve inicialmente 1,3 a 2 TB para o filestore. É uma faixa de planejamento, não requisito oficial.
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.
/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:
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.
O config.php aceita limites para impedir que uploads esgotem o disco:
$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.
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.
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.
Remova pacotes conflitantes apenas se estiverem instalados:
sudo apt remove -y docker.io docker-compose docker-doc podman-docker containerd runc
Adicione o repositório oficial:
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 <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
docker-buildx-plugin docker-compose-plugin
Valide:
sudo systemctl status docker --no-pager
sudo docker run --rm hello-world
sudo docker compose version
É aceitável continuar usando sudo docker. Adicionar um usuário ao grupo docker equivale, na prática, a conceder privilégios de root. Faça isso somente para usuários administrativos confiáveis.
sudo git clone https://github.com/resourcespace/docker.git /opt/resourcespace
sudo chown -R "$USER":"$USER" /opt/resourcespace
cd /opt/resourcespace
Confirme a versão que será incorporada:
grep -n 'releases/' Dockerfile
Na data desta pesquisa, o resultado aponta para releases/11.0.
sudo mkdir -p /srv/resourcespace/mariadb
sudo mkdir -p /srv/resourcespace/filestore
sudo mkdir -p /srv/resourcespace/backups
sudo chown -R 33:33 /srv/resourcespace/filestore
sudo chmod 750 /srv/resourcespace/filestore
sudo chmod 750 /srv/resourcespace/mariadb
sudo chmod 750 /srv/resourcespace/backups
O UID/GID 33 corresponde a www-data na imagem Ubuntu oficial atual. MariaDB inicia como root no container e ajusta o próprio diretório; não aplique UID arbitrário aos dados do banco.
O config.php do repositório vem vazio e é montado no container. Permita que o instalador web o escreva:
sudo chown 33:33 /opt/resourcespace/config.php
sudo chmod 600 /opt/resourcespace/config.php
Depois da instalação, o arquivo continuará legível somente para root no host e www-data no container. Ele contém senha do banco e chaves internas; nunca o publique em Git.
Gere duas senhas diferentes:
openssl rand -base64 36
openssl rand -base64 36
Edite /opt/resourcespace/db.env:
MYSQL_PASSWORD=COLOQUE_A_SENHA_DO_USUARIO_AQUI
MYSQL_ROOT_PASSWORD=COLOQUE_OUTRA_SENHA_AQUI
MYSQL_DATABASE=resourcespace
MYSQL_USER=resourcespace_rw
Proteja o arquivo:
chmod 600 /opt/resourcespace/db.env
Não use espaços ao redor do = e não coloque esse arquivo em repositórios remotos.
Crie /opt/resourcespace/php-upload.ini:
upload_max_filesize = 20G
post_max_size = 20G
max_execution_time = 3600
max_input_time = 3600
memory_limit = 1G
post_max_size deve ser igual ou maior que upload_max_filesize. Definir 20 GB não reserva 20 GB de RAM, mas aceita requisições desse tamanho. Uploads enormes por navegador continuam sujeitos a falhas de rede; faça testes reais antes de prometer confiabilidade.
Não edite o docker-compose.yaml oficial. Crie /opt/resourcespace/compose.production.yaml:
services:
resourcespace:
build:
context: .
container_name: resourcespace
restart: unless-stopped
depends_on:
mariadb:
condition: service_healthy
ports:
- "127.0.0.1:8080:80"
volumes:
- /srv/resourcespace/filestore:/var/www/html/filestore
- ./config.php:/var/www/html/include/config.php
- ./php-upload.ini:/etc/php/8.3/apache2/conf.d/99-uploads.ini:ro
- ./php-upload.ini:/etc/php/8.3/cli/conf.d/99-uploads.ini:ro
networks:
- frontend
- backend
logging:
driver: local
options:
max-size: "20m"
max-file: "5"
mariadb:
image: mariadb:11.4
container_name: resourcespace-mariadb
restart: unless-stopped
env_file:
- db.env
volumes:
- /srv/resourcespace/mariadb:/var/lib/mysql
networks:
- backend
healthcheck:
test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
interval: 10s
timeout: 5s
retries: 10
start_period: 30s
logging:
driver: local
options:
max-size: "20m"
max-file: "5"
networks:
frontend:
backend:
internal: true
Por que esta versão é mais segura:
A tag 11.4 ainda recebe patches dentro da mesma série. Mesmo assim, faça backup e teste antes de atualizar imagens.
cd /opt/resourcespace
sudo docker compose -f compose.production.yaml config
sudo docker compose -f compose.production.yaml build --pull
sudo docker compose -f compose.production.yaml up -d
Observe o estado:
sudo docker compose -f compose.production.yaml ps
sudo docker compose -f compose.production.yaml logs --tail=100 resourcespace
sudo docker compose -f compose.production.yaml logs --tail=100 mariadb
Se estiver acessando de outro computador antes de instalar um proxy, crie um túnel SSH:
ssh -L 8080:127.0.0.1:8080 usuario@servidor
Abra http://127.0.0.1:8080 no computador cliente.
Use:
| Campo | Valor |
|---|---|
| Servidor/IP do banco | mariadb |
| Porta | 3306 |
| Banco | resourcespace |
| Usuário | resourcespace_rw |
| Senha | o valor de MYSQL_PASSWORD |
| Caminho do binário MySQL | deixar vazio |
| URL base | URL HTTPS definitiva, quando já existir |
Crie uma senha longa e exclusiva para o administrador. Não use a senha root do MariaDB como senha do ResourceSpace.
Depois, entre em Administração → Sistema → Verificação da instalação e resolva cada FAIL relevante aos formatos que serão usados.
Não publique a porta 8080 diretamente na internet. Use Caddy, Nginx, Traefik, Nginx Proxy Manager ou um proxy já existente.
server {
listen 443 ssl http2;
server_name dam.exemplo.com;
client_max_body_size 20G;
client_body_timeout 3600s;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_request_buffering off;
}
}
O certificado e o redirecionamento HTTP→HTTPS devem ser configurados por Certbot ou pela solução de proxy usada. No config.php, confirme:
$baseurl = "https://dam.exemplo.com";
Se o serviço for apenas pessoal, uma alternativa mais simples é não criar DNS público: mantenha o bind em localhost e acesse por Tailscale, um proxy interno ou túnel SSH.
Para upload de 20 GB:
upload_max_filesize no PHP;post_max_size no PHP;Cloudflare e outros proxies externos também podem impor limites próprios. Um valor alto no PHP não contorna o limite do serviço colocado à frente.
Adicione ao final de /opt/resourcespace/config.php:
$offline_job_queue = true;
Teste manualmente:
cd /opt/resourcespace
sudo docker compose -f compose.production.yaml exec \
-u www-data resourcespace \
php /var/www/html/pages/tools/offline_jobs.php --max-jobs 2
Depois adicione ao crontab do root no host:
*/5 * * * * cd /opt/resourcespace && /usr/bin/docker compose -f compose.production.yaml exec -T -u www-data resourcespace php /var/www/html/pages/tools/offline_jobs.php --max-jobs 2 >> /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.
ImageMagick e GD geram miniaturas e previews. Arquivos enormes ou formatos incomuns podem consumir muita memória.
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.
Ghostscript e Poppler auxiliam na leitura e geração de previews. PDFs complexos devem ser testados depois da instalação.
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.
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.
Um backup recuperável precisa de três partes inseparáveis:
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.
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.
Siga a regra 3-2-1: três cópias, dois tipos de mídia, uma fora do local.
config.php e o filestore;Não considere o backup válido até realizar uma restauração de teste.
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:
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.
0.0.0.0:8080 sem necessidade;DOCKER-USER quando depender de firewall local.db.env e config.php com permissões restritas;config.php contém segredos.$enable_remote_apis = false;;/var/run/docker.sock em containers;docker;Comandos úteis:
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:
| 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:
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'
| 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 |
config.php como um conjunto.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.
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.
View the original Markdown file
Ideas | What changed | RSS | About | Text version
Pablo Murad <pablomurad@pm.me>