Ir al contenido

Primeros pasos

Artist Alley se distribuye como una imagen de Docker: un único programa en Go que sirve tanto la API como la aplicación web, empaquetado con las herramientas multimedia que usa para generar las vistas previas. 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. Hay tres puntos de partida habituales; elige el que encaje con lo que vas a hacer.

Para echar un vistazo sin instalar nada, usa la demo pública compartida (inicia sesión con demo / demo). Para ejecutar tu propia instancia, lo más rápido es la imagen de Docker publicada. Apúntala a un Postgres (el tuyo, o uno del mismo stack de Compose); necesita PostgreSQL 15 o posterior con la extensión pgvector, y el rol con el que se conecta debe ser superusuario. Consulta la guía de instalación.

El servidor también necesita dos claves. AA_MASTER_KEY cifra las claves de federación y las claves por usuario de la instancia, y el servidor no arranca sin ella. AA_SCRAMBLE_KEY es el «pepper» del hash de contraseñas. Genera ambas una sola vez y reutilízalas cada vez que reinicies o sustituyas el contenedor: una nueva clave AA_SCRAMBLE_KEY hace que ninguna contraseña existente vuelva a funcionar, y perder la clave maestra significa perder todo lo que cifró. Para los pasos siguientes necesitas Docker y OpenSSL.

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 una versión de la página de versiones, sin la v inicial. El usuario y el nombre de la base de datos son artist_alley por defecto; define AA_DB_USER y AA_DB_NAME si los tuyos son distintos.

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_PASSWORD=your-db-password \
-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 esta prueba solo sea accesible desde esta misma máquina. Abre http://localhost:8080 e inicia sesión como admin. En el primer arranque, el servidor crea esa cuenta con una contraseña aleatoria y la imprime en su registro (docker logs artist-alley); consulta Primer inicio de sesión. Cámbiala en cuanto entres.

Lo que subas vive en dos lugares, los registros en Postgres y los archivos en el volumen artist-alley-storage, y las claves de artist-alley.env son necesarias para usarlos. Eliminar y volver a crear el contenedor no supone ningún problema. Para conservar lo que has subido, guarda los tres juntos; ninguno por sí solo basta para restaurar una instalación (Copia de seguridad). La configuración con Docker Compose (y la compilación desde el código fuente) está en la guía de instalación.

Lee la guía de instalación: ejecuta la imagen de Docker publicada detrás de tu proxy inverso existente para el TLS. El servidor en sí habla HTTP plano, así que todo lo que otras personas alcancen a través de una red debería pasar por HTTPS. Fija una versión exacta en lugar de una etiqueta móvil, de modo que las actualizaciones ocurran cuando tú decidas. Hoy la distribución es solo con Docker; están previstos paquetes nativos (.deb/.rpm, Homebrew) y binarios independientes. La guía Para operadores cubre la configuración de Postgres, los backends de almacenamiento (sistema de archivos o cualquier bucket compatible con S3), las copias de seguridad y las actualizaciones.

El desarrollo local usa Docker Compose, y la CI arranca el mismo docker-compose.yml, con un archivo de sobrescritura para su runner compartido que elimina los puertos del host y limita la memoria.

  • Docker con Docker Compose v2, Git y openssl (el script de arranque lo usa para generar los secretos)
  • Suficiente espacio libre en disco para Postgres y los archivos que subas
  • Puertos TCP libres para el stack: por defecto 8088 (la aplicación, a través de nginx), 5173 (el servidor de desarrollo de Vite) y 5433 (Postgres)
Ventana de terminal
git clone https://github.com/Artist-Alley-Org/artist-alley.git
cd artist-alley
./scripts/bootstrap.sh

scripts/bootstrap.sh crea .env a partir de .env.example, genera la contraseña de Postgres y las dos claves necesarias (AA_SCRAMBLE_KEY y AA_MASTER_KEY), y después construye y arranca el stack y espera un momento a que se ponga en marcha. No confirma que todo esté en buen estado; eso lo hacen las comprobaciones de la sección Verificar el stack, más abajo. Si ya existe un .env, lo deja como está. Copiar .env.example a mano no basta: el servidor rechaza al arrancar su clave maestra de ejemplo, y los demás valores de ejemplo no son secretos.

La aplicación se sirve a través de nginx en http://localhost:8088 (NGINX_HTTP_PORT en .env), y el servidor de desarrollo de Vite con recarga en caliente funciona en :5173. El stack de desarrollo define AA_BOOTSTRAP_DEFAULT_ADMIN=1, así que crea admin con la contraseña de desarrollo pública ArtistAlleyMogul; nunca definas esa variable en una instalación real. Edita los archivos Svelte en web/src/ y se recargan en caliente; edita los archivos Go y ejecuta docker compose up -d --build para reconstruir el contenedor de la aplicación.

Ventana de terminal
# Postgres ready:
docker compose exec -T postgres pg_isready -U artist_alley -d artist_alley
# Hit the Go health endpoint:
curl -fsS http://localhost:8088/healthz
# Run the integration tests:
./scripts/test.sh

La CI ejecuta el mismo ./scripts/test.sh contra su stack de Compose; consulta .github/workflows/ci.yml.

  • Referencia de la API: el contrato de la API, con la forma de las solicitudes y respuestas de cada operación.
  • Arquitectura: cómo encajan el servidor, la aplicación web, Postgres y el almacenamiento de archivos.
  • Decisiones de arquitectura: el razonamiento detrás de las decisiones importantes.