Merge pull request #13 from lucasrguerra/docker/cli-image

Docker: CLI image and usage docs

.dockerignore

@@ -0,0 +1,11 @@
+.git
+target
+**/node_modules
+apps/gui/src-tauri
+docs
+scripts
+*.img
+*.guara-session.json
+.claude
+.wolf
+.superpowers

Dockerfile

@@ -0,0 +1,25 @@
+# syntax=docker/dockerfile:1
+# Guará CLI image. Intended for Linux hosts, headless servers and forensic image files.
+# The graphical interface is not served from the container (see docs/docker.md).
+
+FROM rust:1-slim-bookworm AS build
+WORKDIR /src
+# The CLI embeds the web interface at compile time (include_str!), so it needs apps/gui/ui.
+COPY Cargo.toml Cargo.lock ./
+COPY crates crates
+COPY apps/gui/ui apps/gui/ui
+RUN cargo build --release --locked -p guara-cli
+
+FROM debian:bookworm-slim
+# smartmontools gives `guara health` access to SMART data.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends smartmontools ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
+COPY --from=build /src/target/release/guara /usr/local/bin/guara
+LABEL org.opencontainers.image.title="Guará" \
+      org.opencontainers.image.description="File recovery for hard drives, SSDs and USB sticks (CLI)" \
+      org.opencontainers.image.source="https://github.com/lucasrguerra/guara" \
+      org.opencontainers.image.licenses="MIT OR Apache-2.0"
+WORKDIR /data
+ENTRYPOINT ["guara"]
+CMD ["--help"]

README.md

@@ -46,6 +46,8 @@ Every file has a `.sha256` next to it. To build from source: `cargo build --rele
 
 Reading raw disks requires privileges: **administrator** (Windows), `sudo` (Linux and macOS). Even as root, Guará writes sessions, reports and recovered files with the owner and permissions of the user who launched it.
 
+There is also a Docker image of the command line tool, for Linux hosts and for working on image files: see [docs/docker.md](docs/docker.md).
+
 ## Getting started
 
 ```bash

README.pt-BR.md

@@ -46,6 +46,8 @@ Cada arquivo tem um `.sha256` ao lado. Compilar do código: `cargo build --relea
 
 Ler discos brutos exige privilégios: **administrador** (Windows), `sudo` (Linux e macOS). Mesmo como root, o Guará grava sessões, relatórios e arquivos recuperados com o dono e as permissões do usuário que o abriu.
 
+Há também uma imagem Docker do terminal, para hospedeiros Linux e para trabalhar com arquivos de imagem: veja [docs/pt-BR/docker.md](docs/pt-BR/docker.md).
+
 ## Começando
 
 ```bash

docs/docker.md

@@ -0,0 +1,65 @@
+# Running Guará with Docker
+
+[English](docker.md) · [Português](pt-BR/docker.md)
+
+The image contains the `guara` command line tool and `smartctl`. It is useful in three cases:
+
+1. **A Linux server or NAS without a desktop**, with the damaged disk plugged in.
+2. **Forensic image files** (`.img`, E01, AFF4) on any system with Docker, because no device access is needed.
+3. **A reproducible environment** for scripts and CI.
+
+It is **not** the recommended way for most people. For a desktop, use the packages from [Releases](../../../releases).
+
+## Limits
+
+- **Raw devices only work on Linux hosts.** On Windows and macOS, Docker runs inside a virtual machine and does not pass physical disks through. Use an image file instead.
+- **The graphical interface is not served from the container.** `guara ui` listens only on `127.0.0.1` and accepts only that `Host`, by design; opening it to the outside would weaken that protection, so it is not part of the image.
+- Files written to a mounted folder belong to root unless you pass `--user` (possible when you work on image files).
+
+## Build
+
+```bash
+docker build -t guara .
+```
+
+## Image files (any system)
+
+Mount the folder with the image read-only and a separate folder for the results:
+
+```bash
+docker run --rm \
+  -v "$PWD/images:/images:ro" \
+  -v "$PWD/out:/out" \
+  --user "$(id -u):$(id -g)" \
+  guara scan /images/disk.img --session /out/s.json --list
+
+docker run --rm \
+  -v "$PWD/images:/images:ro" -v "$PWD/out:/out" \
+  --user "$(id -u):$(id -g)" \
+  guara recover /out/s.json /out/recovered
+```
+
+## A physical disk (Linux host)
+
+Pass the device **read-only** with the `:r` flag. Docker then blocks writes to it at the kernel level, in addition to Guará never writing to the source:
+
+```bash
+docker run --rm \
+  --device=/dev/sdb:/dev/sdb:r \
+  -v /mnt/other-disk/out:/out \
+  guara scan /dev/sdb --session /out/s.json --list
+```
+
+- The destination must be on **another disk** than `/dev/sdb`.
+- Reading a raw device needs root inside the container, so do not pass `--user` here.
+- To read SMART, `--device` is not enough on some systems; `--cap-add=SYS_RAWIO` is the usual extra.
+- Avoid `--privileged`: it gives the container access to every device.
+
+## Other commands
+
+Everything in the [terminal reference](cli.md) works the same way, for example:
+
+```bash
+docker run --rm --device=/dev/sdb:/dev/sdb:r guara devices
+docker run --rm --device=/dev/sdb:/dev/sdb:r guara health /dev/sdb
+```

docs/pt-BR/docker.md

@@ -0,0 +1,65 @@
+# Usando o Guará com Docker
+
+[English](../docker.md) · **Português**
+
+A imagem traz o terminal `guara` e o `smartctl`. Ela serve em três casos:
+
+1. **Servidor ou NAS Linux sem desktop**, com o disco danificado conectado.
+2. **Arquivos de imagem forense** (`.img`, E01, AFF4) em qualquer sistema com Docker, porque não precisa acessar dispositivo.
+3. **Ambiente reproduzível** para scripts e CI.
+
+**Não** é o caminho recomendado para a maioria das pessoas. No desktop, use os pacotes de [Releases](../../../../releases).
+
+## Limites
+
+- **Dispositivos brutos só funcionam em hospedeiros Linux.** No Windows e no macOS o Docker roda dentro de uma máquina virtual e não repassa discos físicos. Use um arquivo de imagem.
+- **A interface gráfica não é servida pelo container.** O `guara ui` escuta só em `127.0.0.1` e só aceita esse `Host`, de propósito; abrir isso para fora enfraqueceria a proteção, então não faz parte da imagem.
+- Arquivos gravados numa pasta montada pertencem ao root, a menos que você passe `--user` (possível ao trabalhar com arquivos de imagem).
+
+## Construir
+
+```bash
+docker build -t guara .
+```
+
+## Arquivos de imagem (qualquer sistema)
+
+Monte a pasta da imagem somente para leitura e outra pasta para os resultados:
+
+```bash
+docker run --rm \
+  -v "$PWD/imagens:/imagens:ro" \
+  -v "$PWD/saida:/saida" \
+  --user "$(id -u):$(id -g)" \
+  guara scan /imagens/disco.img --session /saida/s.json --list
+
+docker run --rm \
+  -v "$PWD/imagens:/imagens:ro" -v "$PWD/saida:/saida" \
+  --user "$(id -u):$(id -g)" \
+  guara recover /saida/s.json /saida/recuperados
+```
+
+## Disco físico (hospedeiro Linux)
+
+Passe o dispositivo **somente para leitura** com a opção `:r`. O Docker passa a bloquear escritas nele no nível do kernel, além de o Guará nunca gravar na origem:
+
+```bash
+docker run --rm \
+  --device=/dev/sdb:/dev/sdb:r \
+  -v /mnt/outro-disco/saida:/saida \
+  guara scan /dev/sdb --session /saida/s.json --list
+```
+
+- O destino precisa estar em **outro disco** que não seja o `/dev/sdb`.
+- Ler dispositivo bruto exige root dentro do container, então não use `--user` aqui.
+- Para ler o SMART, em alguns sistemas `--device` não basta; o complemento usual é `--cap-add=SYS_RAWIO`.
+- Evite `--privileged`: ele dá ao container acesso a todos os dispositivos.
+
+## Outros comandos
+
+Tudo da [referência do terminal](cli.md) funciona do mesmo jeito, por exemplo:
+
+```bash
+docker run --rm --device=/dev/sdb:/dev/sdb:r guara devices
+docker run --rm --device=/dev/sdb:/dev/sdb:r guara health /dev/sdb
+```