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.
Selección rápida
Sección titulada «Selección rápida»En los comandos de descarga, X.Y.Z es la versión que elijas en la
página de versiones, sin la v inicial.
| Canal | Ideal para | Descarga / instalación |
|---|---|---|
| Docker (GHCR) | La mayoría de usuarios, el camino más rápido | docker pull ghcr.io/artist-alley-org/artist-alley:X.Y.Z |
| Docker Hub | La misma imagen, otro registro | docker pull mscrnt/artist-alley:X.Y.Z |
| Código fuente | Construir tú mismo la imagen | clonar 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).
Requisitos previos
Sección titulada «Requisitos previos»- 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,pgcryptoyuuid-ossp, que vienen con Postgres estándar, pero pgvector se instala por separado. Lo más sencillo es usar una imagenpgvector/pgvectoren lugar depostgresa 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).
Docker (recomendado)
Sección titulada «Docker (recomendado)»Escribe las dos claves en un archivo, una sola vez:
# Run this once, then keep artist-alley.env somewhere safe.umask 077cat > artist-alley.env <<EOFAA_MASTER_KEY=$(openssl rand -base64 32)AA_SCRAMBLE_KEY=$(openssl rand -hex 32)EOFDespué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.
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.ZEl 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.
Primer inicio de sesión
Sección titulada «Primer inicio de sesión»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
=:
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.
Variantes de etiquetas
Sección titulada «Variantes de etiquetas»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.
| Etiqueta | Se actualiza cuando |
|---|---|
:X.Y.Z | una versión concreta (recomendada para fijar) |
:X.Y, :X | pasa a apuntar a la versión más reciente de esa línea |
:latest | pasa a apuntar a cada nueva versión estable (no preliminar) |
:edge | la 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:...).
Ejemplo de Compose
Sección titulada «Ejemplo de Compose»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:
# Run this once in the directory that holds compose.yaml, then keep .env safe.umask 077cat > .env <<EOFAA_MASTER_KEY=$(openssl rand -base64 32)AA_SCRAMBLE_KEY=$(openssl rand -hex 32)DB_PASSWORD=$(openssl rand -hex 16)EOFReemplaza X.Y.Z por la versión.
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.
Compilar desde el código fuente
Sección titulada «Compilar desde el código fuente»git clone https://github.com/Artist-Alley-Org/artist-alleycd artist-alleydocker 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.
Otros canales (previstos)
Sección titulada «Otros canales (previstos)»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.
Verificar las firmas
Sección titulada «Verificar las firmas»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):
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.
Referencia de configuración
Sección titulada «Referencia de configuración»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 dicelocalhost; el valor por defecto del propio binario espostgres. 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
| Variable | Default | Notes |
|---|---|---|
AA_HTTP_ADDR | :8080 |
Postgres
| Variable | Default | Notes |
|---|---|---|
AA_DB_HOST | localhost | |
AA_DB_PORT | 5432 | |
AA_DB_NAME | artist_alley | |
AA_DB_USER | artist_alley | |
AA_DB_PASSWORD | change-me | |
AA_DB_SSLMODE | disable |
Storage backend
| Variable | Default | Notes |
|---|---|---|
AA_STORAGE_BACKEND | fs | fs (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-alley | The 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
| Variable | Default | Notes |
|---|---|---|
AA_LOG_LEVEL | info | |
AA_LOG_FORMAT | json |
Password-hashing pepper
| Variable | Default | Notes |
|---|---|---|
AA_SCRAMBLE_KEY | change-me-to-32-hex-bytes | Mixed into every password hash. Keep it stable across restarts. Generate with: openssl rand -hex 32 |
At-rest encryption master key
| Variable | Default | Notes |
|---|---|---|
AA_MASTER_KEY | required | Base64-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. |