Guia completo

Duas formas de instalar

O OficinaOS é sempre o mesmo programa — a diferença está em como é arrancado no PC da loja. O instalador escolhe o caminho certo sozinho, mas convém perceber os dois:

Docker é a forma normal e recomendada: um programa gratuito que embala a app e a base de dados em «contentores» isolados. Precisa de uma funcionalidade do processador chamada virtualização — a maioria dos PCs a tem, mas alguns trazem-na desligada na BIOS ou não a suportam.

O modo portátil existe para esses PCs: traz tudo embutido num pacote único (a app, a base de dados PostgreSQL e o runtime), sem Docker, sem virtualização e sem serviços Windows.

Instalação normal — Docker (uma vez, ~10 minutos)

Descarregue o instalador ZIP, extraia para uma pasta (ex.: C:\OficinaOS) e faça duplo clique em INSTALAR.bat. Se o Windows Defender SmartScreen avisar: «Mais informações» → «Executar mesmo assim».

O instalador faz tudo sozinho: verifica se o PC consegue correr Docker, instala o Docker Desktop se faltar, gera as palavras-passe e segredos, descarrega a app e arranca. Se pedir para reiniciar, reinicie e corra INSTALAR.bat outra vez.

No fim o browser abre em http://localhost:4000. Primeiro login: utilizador admin, palavra-passe braindead — a app obriga a mudar ambos.

Em Linux ou Mac não há instalador automático — usa-se Docker manualmente:

              git clone https://github.com/braindeadpt/OficinaOS.git
cd OficinaOS && cp .env.example .env
docker compose up -d
docker compose exec app bun run db:seed
            

Erro «virtualization support not detected»

Se o PC não consegue correr Docker, o instalador deteta isso antes de tentar e apresenta duas opções:

• Ativar na BIOS — reiniciar, premir F2/F10/DEL/ESC no arranque, procurar «Intel VT-x», «Virtualization Technology» ou «SVM Mode», ativar e gravar (F10). Depois o caminho Docker normal funciona.
• Instalação portátil — o instalador descarrega oficinaos-portable.zip (~540 MB) e arranca sem Docker: a mesma app, a mesma base de dados, as mesmas funcionalidades.

Dia a dia — ligar, desligar, ficheiros

Depois de instalado, o dia a dia resume-se a duplo clique num ficheiro. Os nomes são iguais nos dois modos — só muda a pasta onde estão:

• Modo Docker: na pasta onde extraiu o instalador.
• Modo portátil: dentro da pasta oficinaos-portable — os dados vivem em data\, os backups em app\uploads\backups.
• Outros dispositivos da loja (tablet, telemóvel, outro PC) não instalam nada — abrem http://<IP-do-PC>:4000 no browser.

Backups e restauro

Os backups são ficheiros comprimidos (.sql.gz) com a base de dados inteira. A app mostra o estado do último backup em Definições → Loja → Backups — funciona igual nos dois modos.

No modo Docker um serviço dedicado faz um backup a cada 24 horas, guarda 14 dias, e opcionalmente copia para armazenamento externo (S3, Backblaze, etc.) e testa o restauro automaticamente.

No modo portátil o backup corre a cada arranque e com BACKUP.bat. Restaurar é com RESTAURAR.bat (repor um ficheiro de backups). Como não há cópia fora do PC automática, copie a pasta app\uploads\backups para um disco externo ou pen — backups no mesmo disco não protegem contra avaria, roubo ou ransomware.

Atualizações

A app avisa no topo quando existe versão nova. Para atualizar, basta duplo clique em ATUALIZAR.bat — faz backup, descarrega a versão nova e reinicia. As migrações da base de dados correm sozinhas.

Diferença prática: no Docker só se descarrega o que mudou; no portátil descarrega-se o pacote inteiro (~540 MB). No modo Docker pode ainda ativar atualizações 100% automáticas (Watchtower).

Na loja — telemóveis, tablets e PCs

Qualquer aparelho ligado à Wi-Fi da loja abre a app no browser — sem instalar nada. Basta escrever o endereço que a instalação dá e fazer login:

Funciona sem internet para o uso do dia a dia. Guarde o endereço nos favoritos — é sempre o mesmo.

              http://192.168.1.33:4000   # o endereço do PC-servidor
            

Ícone no ecrã do telemóvel

Para abrir com um toque, como uma app normal — demora 10 segundos:

• iPhone/iPad: Safari → botão Partilhar → «Adicionar ao ecrã principal»
• Android: Chrome → menu ⋮ → «Adicionar ao ecrã principal»
• Com acesso remoto ligado, o Android chega a oferecer «Instalar aplicação» — instalação real

Fora da loja — acesso remoto

Com o PC da loja ligado, um Cloudflare Tunnel gratuito dá à loja um endereço https:// próprio — sem mexer no router, funciona com qualquer operadora, mesmo as que bloqueiam portas (CGNAT).

Serve para a equipa consultar a app fora da loja e para os links dos clientes — tracking, orçamentos, QR de garantia — abrirem em qualquer lado.

• Criar conta grátis na Cloudflare + um domínio (~10 €/ano)
• No painel Zero Trust: criar o túnel e copiar o token
• Duas linhas no ficheiro .env e reiniciar a app
• Na app: Definições → Loja → URL base de tracking → o endereço público

Privado por defeito

O túnel é opcional: a app funciona a 100% na rede local mesmo sem internet. Os dados dos clientes ficam na loja — a Cloudflare apenas transporta o tráfego encriptado quando o túnel está ligado.

Quem quiser uma barreira extra pode ativar o Cloudflare Access (grátis): email + código antes do login, mantendo as páginas públicas dos clientes abertas.

Problemas comuns

As situações mais frequentes e a resolução de cada uma:

Documentação completa

Este guia cobre o essencial. O repositório no GitHub tem a documentação técnica completa — instalação detalhada, acesso remoto, telemóveis, backups com cópia externa e o funcionamento interno do pacote portátil: