Para operadores
Artist Alley busca ser sencillo de operar: un contenedor de aplicación, una base de datos, una ubicación de almacenamiento. No hay bus de mensajes ni microservicios en el núcleo. La imagen incluye la aplicación junto con las herramientas multimedia que ejecuta para generar vistas previas y miniaturas, entre ellas Node y un Chromium sin interfaz para las vistas previas 3D, así que no hay que ejecutar un servicio de vistas previas aparte. Hoy no se distribuye ningún contenedor de complementos. Las integraciones de IA opcionales son experimentales, permanecen desactivadas hasta que un administrador las configura, y se conectan a servidores de modelos o a APIs de proveedores que tú ejecutas. La búsqueda por imagen está más lejos: parte del código existe, pero todavía no hay una forma compatible de configurarla, y está previsto que llegue con los complementos instalables.
La estructura
Sección titulada «La estructura»- Una sola imagen de contenedor. El binario de Go incrusta la aplicación
web de SvelteKit mediante
go:embed, y la imagen lo empaqueta con las herramientas que invoca en tiempo de ejecución. Actualizar la aplicación significa ejecutar una imagen más reciente. - Solo Postgres. Ni MySQL ni Redis: los registros, la búsqueda de texto completo y los vectores comparten una única base de datos Postgres, y el almacenamiento en caché ocurre dentro de la aplicación. Consulta la ADR 0006 y la ADR 0013.
- Dos niveles de configuración. Los ajustes del proceso (base de datos, claves, backend de almacenamiento, registros) provienen de variables de entorno. Los ajustes que afectan a toda la instalación (sitio, SMTP, proveedores de autenticación, proveedores de IA, apariencia) se guardan en la base de datos y se cambian en la interfaz de administración.
- La copia de seguridad es la base de datos, tus archivos almacenados y
ambas claves.
pg_dump, el volumen de almacenamiento o el bucket de S3, y lasAA_MASTER_KEYyAA_SCRAMBLE_KEYoriginales. Bastan las herramientas estándar; no hay un formato de exportación especial.
Instalar y ejecutar
Sección titulada «Instalar y ejecutar»Las versiones se distribuyen como una imagen de Docker (multiarquitectura, GHCR + Docker Hub). Están previstos paquetes nativos, binarios y una vía con systemd (#242). Sigue la guía de instalación, que tiene todos los pasos de Docker y Compose.
El servidor no arranca sin tres ajustes: AA_DB_PASSWORD, AA_SCRAMBLE_KEY
(el pepper del hash de contraseñas) y AA_MASTER_KEY (la clave de cifrado
en reposo). Genera las dos claves una sola vez, como muestra la guía de
instalación, guárdalas en un lugar seguro y pasa los mismos valores cada vez
que reinicies o sustituyas el contenedor. Una nueva AA_SCRAMBLE_KEY hace
que ninguna contraseña existente vuelva a funcionar, y una AA_MASTER_KEY
nueva o perdida significa perder todo lo que cifró.
Los ejemplos de la guía de instalación publican el puerto en 127.0.0.1, así
que el servidor solo es accesible desde la misma máquina. El servidor habla
HTTP plano; antes de que otras personas lo usen, colócalo detrás de un proxy
inverso que sirva HTTPS.
Canales de publicación
Sección titulada «Canales de publicación»Artist Alley está en fase previa a la versión 1.0 y en pleno desarrollo. Una versión es un número con nombre que puedes fijar, no una declaración de que esté lista para producción; fija una versión exacta para que las actualizaciones ocurran cuando tú decidas.
Las etiquetas de versión no llevan una v inicial: la versión v0.11.0 se
descarga como :0.11.0, y su línea como :0.11.
| Canal | Se actualiza cuando | Para qué usarlo |
|---|---|---|
:X.Y.Z | una versión concreta | fijar una versión (recomendado) |
:X.Y, :X | pasa a apuntar a la versión más reciente de esa línea | seguir una línea de versiones |
:latest | pasa a apuntar a cada nueva versión estable (no preliminar) | probar la versión más reciente |
:edge | la compilación más reciente de dev (continua, no estable) | previsualizar trabajo aún sin publicar |
:edge-<short-sha> | la compilación de un commit de dev, cuando se generó una | fijar una compilación concreta de dev |
Cada etiqueta de aquí es un nombre que el registro puede hacer apuntar a otra
cosa. Para ejecutar exactamente la imagen que probaste, fíjala por digest
(@sha256:...).
Las imágenes edge se construyen a partir de los pushes a dev que cambian la
aplicación. Los commits que solo tocan la documentación no generan imagen, y
una compilación que un push más reciente reemplaza puede no terminar nunca,
así que no todos los commits de dev tienen una etiqueta
:edge-<short-sha>.
Las imágenes de versión son multiarquitectura (amd64 + arm64) y las firma
el workflow de publicación con Sigstore; consulta
Guía de instalación § Verificar las firmas.
Las imágenes :edge son solo amd64 y no están firmadas.
Postgres
Sección titulada «Postgres»Necesitas PostgreSQL 15 o posterior con la extensión pgvector (0.5.0 o
posterior). Artist Alley crea su esquema en la primera ejecución mediante
migraciones goose integradas, y aplica las nuevas cada vez que arranca; no
hay un «contenedor de migración» ni un paso de «crear la base de datos» aparte
más allá del rol y la base de datos iniciales. Reemplaza your-db-password
por una contraseña robusta, y dale a la aplicación el mismo valor como
AA_DB_PASSWORD:
CREATE ROLE artist_alley WITH LOGIN SUPERUSER PASSWORD 'your-db-password';CREATE DATABASE artist_alley OWNER artist_alley;El rol con el que se conecta Artist Alley debe ser superusuario. La primera
migración crea la extensión pgvector y le añade un comentario: Postgres solo
permite que un superusuario cree pgvector (no es una extensión de confianza),
y solo el propietario de la extensión puede comentarla, así que crear la
extensión de antemano con otro superusuario no basta. Las imágenes oficiales
postgres y pgvector/pgvector convierten a POSTGRES_USER en superusuario,
y por eso el ejemplo de Compose de la
guía de instalación funciona
tal cual.
Las migraciones habilitan cuatro extensiones: vector (pgvector, que se
instala por separado; una imagen
pgvector/pgvector es lo más
sencillo) además de pg_trgm, pgcrypto y uuid-ossp, que vienen con
Postgres estándar. El esquema también usa restricciones
UNIQUE NULLS NOT DISTINCT, y por eso PostgreSQL 15 es el mínimo.
Almacenamiento
Sección titulada «Almacenamiento»Dos backends:
-
fs(por defecto): los archivos van bajoAA_STORAGE_FS_ROOT, que la imagen de Docker define como/var/lib/aa-storagedentro del contenedor. Monta ahí un volumen con nombre o un directorio del host, como hacen los ejemplos de la guía de instalación. Sin montaje, Docker crea un volumen anónimo, fácil de perder de vista cuando se sustituye el contenedor. Artist Alley gestiona este directorio por sí mismo; no añadas, renombres ni edites archivos en él a mano. -
s3: cualquier API compatible con S3 (AWS S3, Cloudflare R2, Backblaze B2, MinIO). DefineAA_STORAGE_BACKEND=s3yAA_STORAGE_S3_BUCKET, que es obligatoria. El resto depende de tu proveedor:AA_STORAGE_S3_REGIONvaleus-east-1por defecto; ajústala a tu proveedor y a tu bucket.AA_STORAGE_S3_ENDPOINTnormalmente se deja sin definir para AWS S3. Para otros proveedores, defínela con la URL de S3 del proveedor.AA_STORAGE_S3_ACCESS_KEYyAA_STORAGE_S3_SECRET_KEYse usan solo como pareja. Deja ambas sin definir para usar en su lugar la cadena de credenciales predeterminada del SDK de AWS, como las variables de entorno estándar de AWS o un rol de IAM.AA_STORAGE_S3_USE_PATH_STYLEvaletruepor defecto, lo que encaja con MinIO. Defínela comofalsepara AWS S3, Cloudflare R2 y Backblaze B2.
La guía de instalación § Referencia de configuración enlaza la plantilla anotada, que tiene más detalle.
El almacenamiento es direccionable por contenido: cada archivo almacenado se identifica por su SHA-256, de modo que los mismos bytes se guardan una sola vez en toda la instalación, y los archivos se organizan por hash en lugar de en carpetas de proyecto. La base de datos es lo que conecta esos archivos con las publicaciones, los nombres y los campos, así que el almacenamiento solo sirve junto con la base de datos. Consulta la ADR 0008 - Storage architecture.
Copia de seguridad
Sección titulada «Copia de seguridad»Una copia de seguridad restaurable tiene cuatro partes: la base de datos, los archivos almacenados y las dos claves originales.
Detén primero la aplicación (docker stop artist-alley, o
docker compose stop app), mantenla detenida mientras haces tanto el
volcado de la base de datos como la copia de los archivos almacenados, y
vuelve a iniciarla cuando tengas ambos. Una copia hecha con la aplicación en
marcha exige que la base de datos y los archivos se capturen a la vez, y una
restauración que hayas probado.
Base de datos. Desde una máquina que pueda alcanzar tu servidor Postgres,
sustituyendo postgres.local por su host:
pg_dump -Fc -h postgres.local -U artist_alley -d artist_alley > artist-alley-$(date +%Y%m%d).dumpCon el ejemplo de Compose de la guía de instalación, ejecútalo en cambio
dentro del servicio postgres:
docker compose exec -T postgres pg_dump -Fc -U artist_alley -d artist_alley > artist-alley-$(date +%Y%m%d).dumpArchivos almacenados (originales y todas las vistas previas generadas): dependen de tu backend de almacenamiento:
-
fsen un volumen con nombre (los ejemplos de la guía de instalación): copia el contenido del volumen con un contenedor efímero. Esto escribe en el directorio actual un archivo comprimido del volumenartist-alley-storage:Ventana de terminal docker run --rm \-v artist-alley-storage:/data:ro \-v "$PWD":/backup \alpine tar -czf /backup/artist-alley-storage-$(date +%Y%m%d).tar.gz -C /data .Compose antepone el nombre del proyecto a los nombres de sus volúmenes, así que el volumen
storagedel ejemplo de Compose tiene un nombre comomyproject_storage;docker volume lslo muestra. -
fsen un directorio del host: si montaste un directorio del host, por ejemplo-v /data/artist-alley/storage:/var/lib/aa-storage, copia ese directorio del host, por ejemplorsync -a /data/artist-alley/storage/ backup-host:/backups/artist-alley/storage/./var/lib/aa-storagees la ruta dentro del contenedor, no en el host. -
s3: conserva una copia recuperable de los objetos del bucket que no dependa del propio bucket, por ejemplo una copia programada a otro bucket, cuenta o proveedor desde el que hayas probado a restaurar. Puede que no haya ningún directorio local que copiar. El versionado y la replicación del bucket son una protección adicional útil, pero por sí solos no son una copia de seguridad: un bucket eliminado, una cuenta comprometida o un borrado que la replicación propaga también pueden llevárselos por delante.
Claves: conserva las AA_MASTER_KEY y AA_SCRAMBLE_KEY originales (por
ejemplo, el archivo artist-alley.env o .env de la guía de instalación) en
un lugar seguro y separado del volcado de la base de datos. Sin
AA_MASTER_KEY, los datos cifrados en reposo (por ejemplo los secretos de la
autenticación en dos pasos y las claves de federación) no se pueden leer; sin
AA_SCRAMBLE_KEY, ninguna contraseña existente funciona.
La restauración es la operación inversa: restaura la base de datos
(pg_restore lee el volcado -Fc) y los archivos almacenados, y después
arranca la aplicación con las mismas dos claves. No hay ningún interruptor de
«modo de copia de seguridad». Prueba una restauración en una máquina de
repuesto antes de depender de ella.
Actualizaciones
Sección titulada «Actualizaciones»Haz primero una copia de seguridad restaurable (consulta Copia de seguridad). Las migraciones se ejecutan automáticamente cuando arranca la nueva versión, y solo avanzan: el servidor no tiene ningún comando para deshacerlas, y arrancar una imagen más antigua contra una base de datos ya actualizada no revierte el esquema. Para volver atrás, restaura la copia de seguridad que hiciste antes de actualizar.
Con Docker, sustituye el contenedor por otro que ejecute la nueva versión,
usando el mismo archivo de claves, los mismos ajustes de base de datos y el
mismo volumen de almacenamiento que antes. Con las opciones de la guía de
instalación, y X.Y.Z como la nueva versión:
docker pull ghcr.io/artist-alley-org/artist-alley:X.Y.Zdocker stop artist-alleydocker rm artist-alleydocker run -d \ --name artist-alley \ -p 127.0.0.1:8080:8080 \ --env-file artist-alley.env \ -e AA_DB_HOST=postgres.local \ -e AA_DB_USER=artist_alley \ -e AA_DB_PASSWORD=your-db-password \ -e AA_DB_NAME=artist_alley \ -v artist-alley-storage:/var/lib/aa-storage \ ghcr.io/artist-alley-org/artist-alley:X.Y.ZEliminar el contenedor no toca el volumen con nombre ni la base de datos, así que los archivos almacenados y los registros se conservan. Si lo arrancaste con otras opciones, usa las tuyas.
Con Compose, cambia la etiqueta de image: en compose.yaml por la nueva
versión y, después, en el mismo directorio y con el mismo .env:
docker compose pull appdocker compose up -d appLa política de migraciones (ADR 0046) contempla un último plegado del historial de migraciones en una nueva base de referencia antes de la versión 1.0, y no hay una ruta de actualización compatible que atraviese un plegado. A partir de la 1.0, las migraciones solo se añaden.
Está prevista una vía de actualización con systemd + paquete nativo junto con el trabajo de empaquetado nativo (#242).
Observabilidad
Sección titulada «Observabilidad»- Estado de salud:
GET /healthzyGET /readyzejecutan actualmente la misma comprobación. El servidor hace ping a la base de datos (con un tiempo de espera de dos segundos) y devuelve 200 con un breve estado en JSON (que incluyestatus,version,uptimeydatabase), o 503 con"status": "degraded"cuando la base de datos no responde. Por ejemplo,curl -fsS http://localhost:8080/healthz. - Registros estructurados:
AA_LOG_FORMAT=json(el valor por defecto) para JSON apto para su ingesta, otextpara personas.AA_LOG_LEVELcontrola el nivel de detalle (infopor defecto). - Métricas: está previsto un punto de recolección compatible con Prometheus; consulta la ADR 0033. El servidor todavía no sirve ninguno.
Navegación pública
Sección titulada «Navegación pública»Desactivada por defecto. Una instalación nueva no muestra su biblioteca a los visitantes sin sesión iniciada, y una actualización no lo activa: el ajuste solo se guarda cuando un administrador lo cambia, y la ausencia de un ajuste guardado significa desactivado. Activarla es una decisión deliberada, que se toma con el interruptor Acceso público de la página de ajustes del sitio en la administración.
La aplica el servidor, no se consigue ocultando páginas. Con ella desactivada, el servidor rechaza las solicitudes sin sesión a la API de navegación (recursos y sus archivos, colecciones, el feed de publicaciones, elementos destacados, búsqueda, perfiles públicos e IIIF), en lugar de limitarse a omitir esas páginas de la navegación. Lo que la instalación necesita antes de que alguien inicie sesión, como el inicio de sesión, la configuración del primer arranque y sus ajustes de apariencia, funciona en ambos estados. Las demás rutas conservan sus propias comprobaciones de acceso.
Con ella activada, la regla para los visitantes sin sesión es solo material público: recursos publicados en el nivel público, y colecciones y publicaciones marcadas como Públicas. El contenido de equipo, restringido y bajo embargo no llega a ellos, descargas incluidas. Disponen de una portada con una sección de elementos destacados seleccionados, navegación por recursos y colecciones, búsqueda, páginas de perfil públicas y un feed de publicaciones públicas. Para los usuarios con sesión iniciada, la sensibilidad se aplica al contenido de los archivos y no al listado, de modo que el material restringido que no pueden abrir aparece como un elemento bloqueado en lugar de desaparecer.
La navegación pública llegó en la v0.5.0, desactivada por defecto. Las versiones posteriores completaron las páginas públicas y cerraron lagunas: la v0.6.0 añadió las páginas de perfil públicas, la v0.7.0 corrigió rutas que mostraban trabajo sin publicar a visitantes anónimos, y la v0.10.1 hizo posible marcar una publicación como Pública y abrió el feed de exploración a los visitantes sin sesión. Las notas de versión tienen el detalle. Si ejecutas una biblioteca que debe seguir siendo privada, mantén el acceso público desactivado y mantén el servidor detrás de HTTPS y de tus propios controles de red.
El primer arranque y el inicio de sesión con contraseña funcionan con normalidad con ella desactivada. El SSO genérico (LDAP y SAML) está en el código, pero solo se activa con una función de licencia que hoy no se puede obtener, así que todavía no está disponible.
Federación
Sección titulada «Federación»Las instancias de Artist Alley pueden emparejarse entre sí mediante el protocolo ArchivePub. El emparejamiento establece la conexión; lo que se comparte a través de ella se decide por separado. Hoy, las instancias emparejadas intercambian me gusta y comentarios mediante solicitudes autenticadas. Está previsto compartir recursos y publicaciones entre instancias.
Los ajustes que afectan a toda la instalación (proveedores de autenticación,
proveedores de IA, fuentes y el resto de system_config) nunca se federan:
permanecen en la instancia a la que pertenecen. Los perfiles de usuario
registran de qué servidor procede cada usuario (origin_server_id).
Puedes ejecutar una sola instancia e ignorar por completo la federación.
ADR relevantes para operadores
Sección titulada «ADR relevantes para operadores»- Go como backend objetivo; sin sidecars: la decisión actual de un único servidor Go sobre Postgres. Sustituyó a la ADR histórica Solo Postgres, sin MySQL, que a su vez había sustituido a Adjunct Postgres data model.
- Arquitectura de almacenamiento
- Estrategia de caché
- Base de migraciones + política de plegado
- Observabilidad y telemetría para operadores (métricas y trazas, previstas)