Garage (object storage S3)

O Garage é o object storage S3-compatível da X-Adm, exposto em https://arquivo-api.xadm.biz. É um recurso compartilhado: uma key e um bucket dedicados por app (ex.: onpetro, vantroba).

Regras de uso

• O app fala protocolo S3 padrão (AWS SDK, path-style) — agnóstico de backend.
• Buckets e keys: o app NÃO cria (nada de criar bucket em produção via código a partir do app). Quem provisiona: o time (manual) ou o auth como plano de controle da Central de apps — provisão idempotente via API admin quando a capacidade arquivos é ligada. A key do app precisa de read+write no bucket dele.
• A região configurada no cliente S3 deve bater com o s3_region do Garage (valor atual: garage).
• Credenciais (access key / secret key) entram como variáveis de ambiente marcadas como Secret no Coolify.

Variáveis típicas num app

Variável	Exemplo
S3_ENDPOINT	https://arquivo-api.xadm.biz
S3_BUCKET	vantroba
S3_REGION	garage
S3_ACCESS_KEY / S3_SECRET_KEY	(Secret)

Decisões específicas de cada app sobre o que guardar no Garage (e estratégias de migração) são docs de projeto no repo do app — ver, por exemplo, o modo de armazenamento de XLS do bi-transporte-xls.

O bucket docs-sites

Exceção ao modelo "uma key e um bucket por app": a documentação usa um bucket único (docs-sites, um prefixo por app) com duas keys fixas:

Key	Acesso	Onde está configurada
escrita	write em docs-sites	secrets da organização xadm no Forgejo (DOCS_S3_*) — todos os CIs usam a mesma
leitura	read em docs-sites	envs DOCS_S3_* do site central no Coolify

App novo publicando docs não precisa de key nova — o repo herda os secrets da organização (ver publicar docs).