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.
Quiero probarlo
Sección titulada «Quiero probarlo»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.
# 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 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.
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.ZEl 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.
Quiero instalarlo para un equipo
Sección titulada «Quiero instalarlo para un equipo»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.
Quiero meterme en el código
Sección titulada «Quiero meterme en el código»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.
Requisitos previos
Sección titulada «Requisitos previos»- 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)
Arrancar el stack
Sección titulada «Arrancar el stack»git clone https://github.com/Artist-Alley-Org/artist-alley.gitcd artist-alley./scripts/bootstrap.shscripts/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.
Verificar el stack
Sección titulada «Verificar el stack»# 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.shLa CI ejecuta el mismo ./scripts/test.sh contra su stack de Compose;
consulta
.github/workflows/ci.yml.
Qué leer a continuación
Sección titulada «Qué leer a continuación»- 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.