Ejecutar PrintStash en una Raspberry Pi o un NAS ARM

PrintStash publica imágenes de Docker para linux/amd64 y linux/arm64. Una Raspberry Pi 4 o 5, un NAS ARM o una máquina virtual Linux sobre Apple silicon pueden ejecutar el mismo stack de Compose que un servidor x86. Docker elige la imagen que corresponde.

El compromiso de ARM que antes definía esta página ya no existe. Hasta la v0.11.4, los archivos STEP y STP se guardaban y se descargaban en ARM pero nunca llegaban a tener una previsualización generada. Desde la v0.12.0 la imagen completa también los previsualiza en arm64, así que lo que queda por decidir en una Pi es la memoria, el almacenamiento y cuál de las dos imágenes de la API vas a usar.

Elige un hardware sensato

El mínimo documentado es un núcleo de CPU y 1 GB de RAM. Usa al menos 2 GB cuando la biblioteca contenga mallas grandes o densas. Generar miniaturas es la parte cara; navegar y buscar son mucho más ligeros una vez indexados los archivos.

Mantén la base de datos y los datos de la aplicación en almacenamiento fiable. Un SSD por USB es mejor sitio a largo plazo que una microSD pequeña si la Pi va a estar encendida todo el tiempo. Los archivos de modelo pueden vivir en la bóveda gestionada por PrintStash o en una carpeta del NAS montada e indexada como volumen compartido.

PrintStash limita cuántas mallas se renderizan a la vez y se salta las previsualizaciones que no caben en el presupuesto de memoria disponible. Cuando se salta una previsualización, el archivo se indexa igual. Esto hace usable un equipo con poca memoria, aunque el escaneo inicial tardará más que en un servidor más rápido.

Previsualización de STEP en ARM, y lo que sigue sin probar

PrintStash usa OpenCASCADE para teselar la geometría STEP y STP y poder previsualizarla en el navegador. Hasta la v0.12.0, el paquete que estaba detrás no tenía wheel para Linux ARM, así que la previsualización nunca se ejecutaba en linux/arm64. Cascadio 0.1.1 publica wheels para las dos arquitecturas, y la v0.12.0 lo adopta, así que la imagen completa puede previsualizar y generar miniaturas de STEP en una Pi.

Lee la evidencia por lo que es antes de planificar sobre ella. El proyecto lo verifica teselando un fixture STEP real en una imagen ARM64 bajo QEMU en CI, y dice claramente que la validación nativa en una Raspberry Pi con el hardware representativo de 1 GB sigue pendiente. Eso es compatibilidad de ejecución, no una promesa de rendimiento en tu equipo.

Hay dos límites que se aplican en cualquier arquitectura y que importan más en una Pi que en un servidor. El teselado corre en un proceso hijo desechable con un techo de memoria consciente de cgroups y un tiempo límite de 90 segundos, que puedes subir con VAULT_MESH_STEP_TIMEOUT_SECONDS. Un archivo que se pase de cualquiera de los dos se guarda sin geometría ni previsualización generada en lugar de llevarse por delante el proceso de la API, y el límite genérico de 200 MiB de malla de entrada se aplica antes de todo eso. En una Pi de 1 GB, cuenta con que el ensamblaje grande sea el que vuelva sin imagen.

El archivo CAD original no se modifica ni se rechaza en ninguno de los dos casos. Las previsualizaciones de STL, 3MF, OBJ, G-code y BGCODE funcionan en ARM como siempre.

Instalar en una Raspberry Pi

Empieza con una instalación de Raspberry Pi OS de 64 bits y un Docker actualizado. Después descarga el archivo de Compose y levántalo:

mkdir printstash && cd printstash
curl -O https://raw.githubusercontent.com/xiao-villamor/PrintStash/main/docker-compose.yml

docker compose up -d

No hay nada que editar antes: todas las variables de ese archivo tienen un valor por defecto que funciona, y la API genera su propio secreto de firma en el primer arranque en lugar de usar el marcador público. El primer arranque sí necesita un token de configuración, que la API escribe en su log mientras la bóveda está sin configurar:

docker compose logs api | grep "setup token"

Abre http://<pi-ip>:3000, introduce el token y completa el asistente de configuración. No hay cuenta de administrador por defecto.

Comprueba los contenedores antes de importar archivos:

docker compose ps
docker compose logs --tail=100 api

La guía de instalación tiene los requisitos actuales y las opciones de producción.

Imagen completa o imagen lite

Desde la v0.12.0 la API viene en dos variantes, y un equipo justo de recursos es exactamente donde importa la elección. printstash-api es la imagen por defecto y lo lleva todo. printstash-api-lite prescinde de Chromium, que es lo que permite importar con ayuda del navegador las páginas que bloquean una petición HTTP normal, y prescinde también del teselado de OpenCASCADE que genera las previsualizaciones de STEP. Mantiene las miniaturas de malla mediante NumPy, Pillow y Trimesh, así que las previsualizaciones de STL, 3MF y OBJ no cambian.

La recompensa es el tamaño: CI rechaza la compilación si lite no es al menos 700 MiB más pequeña que la completa, y también comprueba que el arranque no se vuelva más lento. En una Pi descargando imágenes por una conexión doméstica hacia una tarjeta SD, esa es la diferencia entre una actualización rápida y una larga.

Cambiar es cuestión del archivo de Compose, no de un ajuste. docker-compose.light.yml descarga la imagen lite, así que descarga ese archivo en lugar del predeterminado. También quita las variables de S3 y de destino de copias de seguridad, lo que encaja con una Pi sobre SQLite y disco local.

Elige lite si tus fuentes CAD son mallas y sueles importar subiendo archivos o pegando enlaces directos. Quédate en la completa si guardas archivos STEP o STP y quieres verlos en el navegador, o si dependes de capturar páginas de modelos que necesitan un navegador real para cargarse.

Monta el almacenamiento del NAS con cuidado

Para una carpeta del NAS, monta primero el recurso compartido en el host de Docker y luego enlaza esa ruta dentro del contenedor de la API. No apuntes un volumen compartido a una ruta que aparece vacía porque un montaje SMB o NFS ha fallado. PrintStash comprueba si un volumen ya indexado aparece vacío sin motivo, pero el montaje del host debería vigilarse igualmente.

Confirma que el contenedor ve los archivos esperados antes de lanzar un escaneo:

docker compose exec api ls /mnt/nas/3d

Da permiso de lectura y escritura a la API solo si PrintStash debe añadir subidas o revisiones a esa carpeta. Los montajes de solo lectura están bien para un archivo histórico que solo hay que indexar. La guía de volúmenes compartidos cubre el montaje en Compose y la política de escritura en detalle.

Qué esperar de una Pi

Una Pi encaja bien con una biblioteca personal cuando la velocidad de importación no es urgente. Escanea primero una carpeta más pequeña y vigila el uso de memoria mientras se generan las miniaturas. Los STL densos y los lotes grandes van a tardar, pero la interfaz sigue siendo útil una vez cacheado el trabajo inicial.

Para una biblioteca grande, varios usuarios u otros contenedores que consuman memoria en el mismo equipo, usa una Pi 5 con más RAM o mueve el servicio a una máquina x86 pequeña. Los archivos pueden quedarse en el NAS en cualquiera de los dos casos.