Ir al contenido

Instalar Artist Alley

Artist Alley se distribuye como una imagen de Docker: un único binario de Go con el frontend de SvelteKit incrustado mediante go:embed, empaquetado junto con las herramientas de ejecución que invoca. Aporta tu propio Postgres y un directorio de almacenamiento con permisos de escritura o un bucket compatible con S3. Artist Alley está en fase previa a la versión 1.0 y en pleno desarrollo, así que todavía se están incorporando funciones y aún no está listo para producción.

Las imágenes de versión son multiarquitectura (amd64 + arm64) y se publican tanto en GHCR como en Docker Hub a partir de la misma compilación; las imágenes continuas :edge son solo amd64. Están previstos paquetes nativos y binarios; consulta Otros canales.

En los comandos de descarga, X.Y.Z es la versión que elijas en la página de versiones, sin la v inicial.

CanalIdeal paraDescarga / instalación
Docker (GHCR)La mayoría de usuarios, el camino más rápidodocker pull ghcr.io/artist-alley-org/artist-alley:X.Y.Z
Docker HubLa misma imagen, otro registrodocker pull mscrnt/artist-alley:X.Y.Z
Código fuenteConstruir tú mismo la imagenclonar el repositorio, docker build (consulta Compilar desde el código fuente)

Las imágenes de versión están firmadas con Sigstore, y las imágenes :edge no lo están (cosign verify, consulta Verificar las firmas).

  • Docker para ejecutar la imagen, y OpenSSL para generar las claves que se describen más abajo.
  • PostgreSQL 15 o posterior, con la extensión pgvector (0.5.0 o posterior). Aporta el tuyo; Artist Alley crea su propio esquema en la primera ejecución mediante migraciones integradas. Esas migraciones también habilitan pg_trgm, pgcrypto y uuid-ossp, que vienen con Postgres estándar, pero pgvector se instala por separado. Lo más sencillo es usar una imagen pgvector/pgvector en lugar de postgres a secas, como en el ejemplo de Compose de más abajo. El rol de base de datos con el que se conecta Artist Alley debe ser superusuario; consulta Para operadores.
  • Un directorio de almacenamiento (blobs binarios + miniaturas generadas) o un bucket compatible con S3 (MinIO, Backblaze B2, Cloudflare R2, AWS S3; todos compatibles mediante AA_STORAGE_BACKEND=s3).
  • Un pepper para el hash de contraseñas (AA_SCRAMBLE_KEY): openssl rand -hex 32. Mantenlo estable entre reinicios y sustituciones del contenedor; uno nuevo hace que ninguna contraseña existente vuelva a funcionar.
  • Una clave de cifrado en reposo (AA_MASTER_KEY): openssl rand -base64 32. Es obligatoria al arrancar; cifra las claves de federación y las claves por usuario, y perderla significa perder todo lo que cifró.

Genera ambas claves una sola vez, guárdalas en un lugar seguro y reutilízalas cada vez que reinicies o sustituyas el contenedor. Una instalación restaurable es la base de datos, los archivos almacenados y las dos claves, todo junto (Copia de seguridad).


Escribe las dos claves en un archivo, una sola vez:

Ventana de terminal
# Run this once, then keep artist-alley.env somewhere safe.
umask 077
cat > artist-alley.env <<EOF
AA_MASTER_KEY=$(openssl rand -base64 32)
AA_SCRAMBLE_KEY=$(openssl rand -hex 32)
EOF

Después, arranca el contenedor con ese archivo. Los valores que hay que reemplazar son marcadores de posición: postgres.local y your-db-password son el host y la contraseña de tu base de datos, y X.Y.Z es la versión.

Ventana de terminal
docker 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.Z

El 127.0.0.1 en la asignación de puertos hace que el servidor solo sea accesible desde esta misma máquina. El servidor habla HTTP plano, así que, cuando otras personas necesiten acceder a él, colócalo detrás de un proxy inverso que sirva HTTPS en lugar de publicar el puerto directamente.

En el primer arranque, el servidor crea una cuenta admin con una contraseña aleatoria y la imprime en su registro, entre dos líneas de signos =:

Ventana de terminal
docker logs artist-alley 2>&1 | grep -A3 "FIRST-BOOT"

Abre http://localhost:8080, inicia sesión como admin con esa contraseña y cámbiala. En una instalación normal no hay ningún asistente de configuración que recorrer. AA_BOOTSTRAP_DEFAULT_ADMIN=1 crea en su lugar admin con una contraseña de desarrollo pública; nunca lo definas en una instalación real.

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.

EtiquetaSe actualiza cuando
:X.Y.Zuna versión concreta (recomendada para fijar)
:X.Y, :Xpasa a apuntar a la versión más reciente de esa línea
:latestpasa a apuntar a cada nueva versión estable (no preliminar)
:edgela compilación más reciente de dev (continua, no estable)
:edge-<short-sha>la compilación de un commit de dev. Los commits que solo tocan la documentación no generan imagen.

Una etiqueta es un nombre que el registro puede hacer apuntar a otra cosa. Para fijar exactamente los bytes que probaste, descarga mejor por digest (@sha256:...).

Pon las dos claves y una contraseña de base de datos en un archivo .env junto a compose.yaml, generado una sola vez y conservado:

Ventana de terminal
# Run this once in the directory that holds compose.yaml, then keep .env safe.
umask 077
cat > .env <<EOF
AA_MASTER_KEY=$(openssl rand -base64 32)
AA_SCRAMBLE_KEY=$(openssl rand -hex 32)
DB_PASSWORD=$(openssl rand -hex 16)
EOF

Reemplaza X.Y.Z por la versión.

compose.yaml
services:
app:
image: ghcr.io/artist-alley-org/artist-alley:X.Y.Z
ports: ["127.0.0.1:8080:8080"]
environment:
AA_DB_HOST: postgres
AA_DB_USER: artist_alley
AA_DB_PASSWORD: ${DB_PASSWORD:?set in .env}
AA_DB_NAME: artist_alley
AA_SCRAMBLE_KEY: ${AA_SCRAMBLE_KEY:?set in .env}
AA_MASTER_KEY: ${AA_MASTER_KEY:?set in .env}
volumes:
- storage:/var/lib/aa-storage
depends_on:
postgres:
condition: service_healthy
restart: unless-stopped
postgres:
image: pgvector/pgvector:pg16
environment:
POSTGRES_DB: artist_alley
POSTGRES_USER: artist_alley
POSTGRES_PASSWORD: ${DB_PASSWORD:?set in .env}
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U artist_alley -d artist_alley"]
interval: 5s
timeout: 5s
retries: 20
restart: unless-stopped
volumes:
storage:
pgdata:

Después, ejecuta docker compose up -d. La aplicación espera a que Postgres indique que está en buen estado antes de arrancar, y su contraseña del primer arranque está en docker compose logs app (consulta Primer inicio de sesión). Los volúmenes pgdata y storage y el archivo .env forman juntos la instalación; conserva los tres.

Ventana de terminal
git clone https://github.com/Artist-Alley-Org/artist-alley
cd artist-alley
docker build -t artist-alley:local .

Es la misma compilación multietapa que usan las imágenes publicadas: construye el frontend de SvelteKit con npm, lo incrusta en el binario de Go y empaqueta el binario con las herramientas que invoca en tiempo de ejecución (ffmpeg, ImageMagick, Ghostscript, Chromium y otras). En tu máquina solo necesitas Git y Docker con BuildKit, que requieren los montajes de caché del Dockerfile. Ejecuta el resultado exactamente igual que la imagen publicada, usando artist-alley:local como nombre de la imagen.

Todavía no hay una compilación compatible de un binario nativo independiente: el binario depende de esas herramientas de ejecución, que solo proporciona la imagen. Consulta Otros canales.


Hoy las versiones se distribuyen solo con Docker. La distribución nativa (paquetes .deb / .rpm con una unidad de systemd reforzada, binarios estáticos para Linux/macOS/Windows y un tap de Homebrew) está prevista y se sigue en la incidencia #242. Hasta entonces, ejecuta la imagen de Docker (detrás de tu proxy inverso existente para el TLS) o compila desde el código fuente.


Las imágenes de Docker se firman sin clave (keyless) con Sigstore. Reemplaza X.Y.Z por una versión, sin la v (por ejemplo 0.11.0):

Ventana de terminal
cosign verify ghcr.io/artist-alley-org/artist-alley:X.Y.Z \
--certificate-identity-regexp "https://github.com/Artist-Alley-Org/artist-alley/.*" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"

El workflow de publicación firma la imagen bajo cada etiqueta que publica, incluido el nombre de Docker Hub, así que la misma comprobación sirve para mscrnt/artist-alley:X.Y.Z. Las imágenes :edge no están firmadas.


Los ajustes del proceso provienen de variables de entorno: pásalas al contenedor con opciones -e o un bloque environment: de Compose (un env_file también funciona). Los ajustes que afectan a toda la instalación, como el nombre del sitio, el SMTP, los proveedores de autenticación, los proveedores de IA y la apariencia, se guardan en la base de datos y se cambian en la interfaz de administración, no mediante el entorno.

La tabla de más abajo se construye a partir de docs/install/config/aa.env.example, una plantilla que el binario no lee. Enumera las variables que la plantilla define por defecto; las opcionales, como las del almacenamiento S3, están documentadas en la propia plantilla. Cuando la tabla y el binario no coinciden, manda el comportamiento del binario.

La columna Default (valor por defecto) muestra los valores de ejemplo de la plantilla, no los valores de reserva del binario ni de la imagen, y sus contraseñas y claves son marcadores de posición que hay que reemplazar. Esto es lo que importa para los comandos de esta página:

  • AA_DB_HOST: la plantilla dice localhost; el valor por defecto del propio binario es postgres. Defínelo con el host de tu base de datos.
  • AA_STORAGE_FS_ROOT: la plantilla dice /var/lib/artist-alley; la imagen de Docker define /var/lib/aa-storage, la ruta que montan los ejemplos.
  • AA_DB_PASSWORD, AA_SCRAMBLE_KEY, AA_MASTER_KEY: los valores de la plantilla son marcadores de posición. El servidor rechaza al arrancar la clave maestra de ejemplo; genera ambas claves como se describe más arriba.

La tabla generada que aparece a continuación es una referencia técnica y se mantiene en inglés, incluidos los encabezados de columna y las descripciones.

HTTP listener

VariableDefaultNotes
AA_HTTP_ADDR:8080

Postgres

VariableDefaultNotes
AA_DB_HOSTlocalhost
AA_DB_PORT5432
AA_DB_NAMEartist_alley
AA_DB_USERartist_alley
AA_DB_PASSWORDchange-me
AA_DB_SSLMODEdisable

Storage backend

VariableDefaultNotes
AA_STORAGE_BACKENDfsfs (default) stores byte blobs under AA_STORAGE_FS_ROOT. s3 uses any S3-compatible API (AWS, MinIO, Backblaze B2, R2, …).
AA_STORAGE_FS_ROOT/var/lib/artist-alleyThe Docker image sets this to /var/lib/aa-storage (the image’s VOLUME). A binary run without the variable uses /var/lib/artist-alley/storage. Set it to wherever your storage is mounted.

Logging

VariableDefaultNotes
AA_LOG_LEVELinfo
AA_LOG_FORMATjson

Password-hashing pepper

VariableDefaultNotes
AA_SCRAMBLE_KEYchange-me-to-32-hex-bytesMixed into every password hash. Keep it stable across restarts. Generate with: openssl rand -hex 32

At-rest encryption master key

VariableDefaultNotes
AA_MASTER_KEYrequiredBase64-encoded 32 bytes; generate it with openssl rand -base64 32. (required) The service exits at startup without it. Losing this key means losing access to everything it encrypts; back it up.