Saltar a contenido

Imagenes de Guide Library en Cloudflare R2

Esta guia explica como preparar imagenes para la biblioteca sin guardarlas en GitHub.

Estado previsto

  • Bucket R2: curiositas-library
  • Dominio publico: https://library-assets.curiositasmundus.com
  • Originales grandes: se conservan fuera del repo, por ejemplo en pCloud.
  • R2 guarda solo versiones web utiles para la app.

Archivo local de claves

En la raiz del repo hay un archivo local:

.env.r2

Abre ese archivo, pega los datos de Cloudflare y guarda.

No subir .env.r2 a GitHub. Esta en .gitignore.

Valores esperados:

R2_ACCOUNT_ID=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET=curiositas-library
R2_ENDPOINT=https://<ACCOUNT_ID>.r2.cloudflarestorage.com
R2_PUBLIC_BASE_URL=https://library-assets.curiositasmundus.com
R2_DEFAULT_IMAGE_MAX_WIDTH=1800
R2_DEFAULT_IMAGE_QUALITY=82

Tambien queda una plantilla segura versionada:

.env.r2.example

Como rellenar R2_ACCOUNT_ID y R2_ENDPOINT

En Cloudflare, al crear un token de R2, aparecen varios datos:

  • Access Key ID: va en R2_ACCESS_KEY_ID.
  • Secret Access Key: va en R2_SECRET_ACCESS_KEY.
  • Endpoint S3, con forma https://<account-id>.r2.cloudflarestorage.com: va en R2_ENDPOINT.

El R2_ACCOUNT_ID es la parte del endpoint que aparece antes de .r2.cloudflarestorage.com.

Ejemplo ficticio:

Endpoint mostrado por Cloudflare:
https://abc123def456.r2.cloudflarestorage.com

R2_ACCOUNT_ID=abc123def456
R2_ENDPOINT=https://abc123def456.r2.cloudflarestorage.com

Importante:

  • R2_ENDPOINT no debe incluir /curiositas-library al final.
  • El valor llamado Token value sirve para la API de Cloudflare, pero no hace falta para este script S3.
  • No pegar claves reales en GitHub, chats, capturas compartidas ni documentos versionados.

Convencion de carpetas

Usar rutas estables y sin espacios:

guide-library/belgica/bruselas/grand-place/ayuntamiento.jpg
guide-library/belgica/lovaina/grote-markt/ayuntamiento.jpg
guide-library/belgica/amberes/red-star-line/museo.jpg

Reglas:

  • Minusculas.
  • Sin tildes.
  • Sin espacios.
  • Usar guiones.
  • Mantener contexto: pais / ciudad / tema o parada / archivo.

Tamano recomendado

Para la app:

  • Fotos normales: 1600-1800 px de ancho maximo.
  • Imagenes que se quieran ensenar en tablet o imprimir en A4 sencillo: 2000-2400 px de ancho maximo.
  • Calidad JPG inicial: 80-85.

Los originales grandes siguen en pCloud. R2 no necesita guardar el master gigante.

Instalar dependencias locales

Solo hace falta para subir u optimizar imagenes desde esta maquina:

py -3.14 -m pip install -r requirements-assets.txt

Subir una imagen

Ejemplo:

py -3.14 scripts/r2_upload_image.py "C:\ruta\foto.jpg" "guide-library/belgica/lovaina/grote-markt/ayuntamiento.jpg"

El script:

  • lee .env.r2;
  • reduce la imagen si supera el ancho maximo;
  • optimiza JPG/PNG/WebP;
  • sube el resultado a R2;
  • devuelve la URL publica para pegarla en Markdown.

Usar imagen en Markdown

Imagen simple:

![Ayuntamiento de Lovaina](https://library-assets.curiositasmundus.com/guide-library/belgica/lovaina/grote-markt/ayuntamiento.jpg)

Imagen con pie:

<figure markdown>
  ![Ayuntamiento de Lovaina](https://library-assets.curiositasmundus.com/guide-library/belgica/lovaina/grote-markt/ayuntamiento.jpg)
  <figcaption>Ayuntamiento de Lovaina, ejemplo de gotico brabantino.</figcaption>
</figure>

Donde poner imagenes en la biblioteca

  • Manuales: imagenes amplias con pie de foto y contexto.
  • Guiones: solo imagenes utiles para contar una parada.
  • Fichas rapidas: una miniatura o imagen clave si ayuda durante el tour.
  • Indices rapidos: evitar imagenes salvo necesidad clara.

Privacidad

Si el bucket o dominio es publico, cualquiera que tenga la URL puede abrir la imagen.

Si en el futuro la biblioteca se vuelve privada o de pago, revisar:

  • Cloudflare Access para library-assets.curiositasmundus.com;
  • o servir imagenes mediante Worker con control de acceso;
  • o separar assets publicos y privados en buckets distintos.