Merge pull request #19 from exelearning/17-build-docker-image

Version jump to 4.0.0 and new Docker image

Author: eXeLearningProject

.dockerignore

@@ -0,0 +1,13 @@
+.git
+.github
+.vscode
+.idea
+.claude
+node_modules
+scripts
+docs
+server.js
+package.json
+package-lock.json
+*.md
+IDEAS*.md

.env.dist

@@ -0,0 +1,19 @@
+# eXeViewer – deployment configuration
+# Copy this file to .env and edit the values you need.
+# Variables not set here keep the application defaults.
+
+# Google Apps Script proxy URL for Google Drive support.
+# Leave empty to disable.
+GAS_PROXY_URL=
+
+# Automatically restore the last viewed content on page load.
+AUTO_RESTORE_CONTENT=true
+
+# Open external links in a new tab (recommended when embedded in an iframe).
+OPEN_EXTERNAL_LINKS_IN_NEW_WINDOW=true
+
+# Reject ZIP files that are not valid eXeLearning packages.
+VALIDATE_EXE_CONTENT=true
+
+# Show the download button enabled by default in the share dialog.
+ALLOW_DOWNLOAD_BY_DEFAULT=true

.github/workflows/docker.yml

@@ -0,0 +1,51 @@
+name: Publish Docker image
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.gitignore

@@ -1,6 +1,9 @@
 # Node modules
 node_modules/
 
+# Local deployment config (copy from .env.dist)
+.env
+
 # OS generated files
 .DS_Store
 Thumbs.db

CHANGELOG.md

@@ -1,12 +1,14 @@
 # CHANGELOG
 
-## v1.0.4 – 2026-04-13
+## v4.0.0-rc1 – 2026-04-14
 
+- Version jump to 4.0.0 to align numbering with eXeLearning for consistency across related projects.
+- Add Docker image (published to GitHub Container Registry) for optional containerized deployment.
+- Add a deployment configuration file to override default settings defined in `app.js`.
 - Request persistent storage to prevent the browser from evicting IndexedDB content.
 - Improve Web Worker lifecycle management by properly terminating the worker, clearing its reference and standardizing error reporting.
 - Align license declaration for consistency across the project.
 - Improve error handling and user feedback for storage-related failures, including insufficient storage space conditions.
-- Add a deployment configuration file to override default settings defined in `app.js`.
 
 ---
 

Dockerfile

@@ -0,0 +1,16 @@
+FROM nginx:alpine
+
+COPY index.html manifest.json sw.js /usr/share/nginx/html/
+COPY css/   /usr/share/nginx/html/css/
+COPY js/    /usr/share/nginx/html/js/
+COPY lang/  /usr/share/nginx/html/lang/
+COPY img/   /usr/share/nginx/html/img/
+COPY vendor/ /usr/share/nginx/html/vendor/
+
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+
+COPY docker/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+EXPOSE 80
+ENTRYPOINT ["/entrypoint.sh"]

README.md

@@ -117,6 +117,54 @@ The application will work on:
 
 For the share functionality to work, the application must be served over HTTPS (or HTTP on localhost).
 
+### Docker
+
+A pre-built image is published to the GitHub Container Registry on every release. It uses nginx on Alpine Linux (~8 MB base image).
+
+#### Quick start
+
+```bash
+docker run -p 8080:80 ghcr.io/exelearning/exeviewer:latest
+```
+
+Then open `http://localhost:8080` in your browser.
+
+#### Docker Compose (recommended)
+
+Download the provided `docker-compose.yml` and the configuration template:
+
+```bash
+curl -O https://raw.githubusercontent.com/exelearning/exeviewer/main/docker-compose.yml
+curl -O https://raw.githubusercontent.com/exelearning/exeviewer/main/.env.dist
+cp .env.dist .env
+```
+
+Edit `.env` if you need to customise any settings (e.g. Google Drive proxy), then start the container:
+
+```bash
+docker compose up -d
+```
+
+#### Configuration via environment variables
+
+Instead of editing `js/config.js`, Docker deployments are configured through environment variables, either in `.env` or in the `environment:` block of your Compose file:
+
+| Variable | Default | Description |
+|---|---|---|
+| `GAS_PROXY_URL` | _(empty)_ | Google Apps Script proxy URL for Google Drive support |
+| `AUTO_RESTORE_CONTENT` | `true` | Restore last viewed content on page load |
+| `OPEN_EXTERNAL_LINKS_IN_NEW_WINDOW` | `true` | Open external links in a new tab |
+| `VALIDATE_EXE_CONTENT` | `true` | Reject ZIPs that are not valid eXeLearning packages |
+| `ALLOW_DOWNLOAD_BY_DEFAULT` | `true` | Show download button enabled by default in share dialog |
+
+Variables not set in `.env` keep their default values. You only need to include the ones you want to change.
+
+#### HTTPS
+
+**HTTPS is required.** The Service Worker (the core mechanism that serves extracted ZIP content) will not register on non-secure origins. This is a browser security restriction, not an eXeViewer limitation. The only exception is `localhost`, which works without HTTPS for local development.
+
+For production deployments, ensure TLS is terminated before reaching the browser. The most common approach is a reverse proxy in front of the container (Nginx, Traefik, Caddy, etc.), but cloud load balancers or any other TLS termination point work equally well.
+
 ### Running locally without a web server
 
 If you don't have a web server installed, you can use the included `server.js`:
@@ -261,26 +309,32 @@ Firefox doesn't support PWA installation natively. Use the [PWAs for Firefox](ht
 
 ```
 exeviewer/
-├── index.html          # Main application page
-├── manifest.json       # PWA manifest
-├── sw.js               # Service Worker
-├── server.js           # Development server (Bun/Node.js)
-├── package.json        # Project configuration
+├── index.html              # Main application page
+├── manifest.json           # PWA manifest
+├── sw.js                   # Service Worker
+├── server.js               # Development server (Bun/Node.js)
+├── package.json            # Project configuration
+├── Dockerfile              # Docker image definition
+├── nginx.conf              # nginx configuration for the Docker image
+├── docker-compose.yml      # Docker Compose example
+├── .env.dist            # Environment variable template for Docker deployments
+├── docker/
+│   └── entrypoint.sh       # Generates js/config.js from environment variables at startup
 ├── css/
-│   └── styles.css      # Custom styles
+│   └── styles.css          # Custom styles
 ├── js/
-│   ├── app.js          # Main application logic
-│   ├── config.js       # Deployment configuration (overrides defaults in app.js)
-│   ├── i18n.js         # Internationalization module
-│   └── zip.worker.js   # Web Worker for ZIP extraction
+│   ├── app.js              # Main application logic
+│   ├── config.js           # Deployment configuration (overrides defaults in app.js)
+│   ├── i18n.js             # Internationalization module
+│   └── zip.worker.js       # Web Worker for ZIP extraction
 ├── lang/
-│   ├── en.json         # English translations
-│   └── es.json         # Spanish translations
-├── img/                # Icons and images
-├── vendor/             # Third-party libraries
-│   ├── bootstrap/      # Bootstrap 5.3.2
-│   ├── bootstrap-icons/# Bootstrap Icons 1.11.1
-│   └── fflate/         # fflate 0.8.2
+│   ├── en.json             # English translations
+│   └── es.json             # Spanish translations
+├── img/                    # Icons and images
+├── vendor/                 # Third-party libraries
+│   ├── bootstrap/          # Bootstrap 5.3.2
+│   ├── bootstrap-icons/    # Bootstrap Icons 1.11.1
+│   └── fflate/             # fflate 0.8.2
 └── scripts/
     └── generate-icons.js   # Icon generation script (requires Node.js + sharp)
 ```

README_es.md

@@ -117,6 +117,54 @@ La aplicación funcionará en:
 
 Para que la opción de compartir funcione, la aplicación se debe servir por HTTPS (o HTTP en localhost).
 
+### Docker
+
+Se publica una imagen precompilada en el GitHub Container Registry con cada nueva versión. Usa nginx sobre Alpine Linux (~8 MB de imagen base).
+
+#### Inicio rápido
+
+```bash
+docker run -p 8080:80 ghcr.io/exelearning/exeviewer:latest
+```
+
+Abre `http://localhost:8080` en tu navegador.
+
+#### Docker Compose (recomendado)
+
+Descarga el `docker-compose.yml` incluido y la plantilla de configuración:
+
+```bash
+curl -O https://raw.githubusercontent.com/exelearning/exeviewer/main/docker-compose.yml
+curl -O https://raw.githubusercontent.com/exelearning/exeviewer/main/.env.dist
+cp .env.dist .env
+```
+
+Edita `.env` si necesitas personalizar algún parámetro (por ejemplo, la URL del proxy de Google Drive) y arranca el contenedor:
+
+```bash
+docker compose up -d
+```
+
+#### Configuración mediante variables de entorno
+
+En lugar de editar `js/config.js`, los despliegues con Docker se configuran mediante variables de entorno, ya sea en el fichero `.env` o en el bloque `environment:` de tu fichero Compose:
+
+| Variable | Valor por defecto | Descripción |
+|---|---|---|
+| `GAS_PROXY_URL` | _(vacío)_ | URL del proxy de Google Apps Script para Google Drive |
+| `AUTO_RESTORE_CONTENT` | `true` | Restaurar el último contenido visto al cargar la página |
+| `OPEN_EXTERNAL_LINKS_IN_NEW_WINDOW` | `true` | Abrir los enlaces externos en una pestaña nueva |
+| `VALIDATE_EXE_CONTENT` | `true` | Rechazar ZIP que no sean paquetes eXeLearning válidos |
+| `ALLOW_DOWNLOAD_BY_DEFAULT` | `true` | Mostrar el botón de descarga activado por defecto en el diálogo de compartir |
+
+Las variables no definidas en `.env` conservan sus valores por defecto; solo es necesario incluir las que se quieran cambiar.
+
+#### HTTPS
+
+**HTTPS es obligatorio.** El Service Worker (el mecanismo central que sirve el contenido ZIP extraído) no se registra en orígenes no seguros. Es una restricción del navegador, no de eXeViewer. La única excepción es `localhost`, que funciona sin HTTPS para desarrollo local.
+
+En despliegues en producción, asegúrate de que TLS se termina antes de que la petición llegue al navegador. Lo más habitual es un proxy inverso delante del contenedor (Nginx, Traefik, Caddy, etc.), pero también funcionan los balanceadores de carga o cualquier otro punto de terminación TLS.
+
 ### Ejecución local sin servidor web
 
 Si no tienes un servidor web instalado, puedes usar el `server.js` incluido:
@@ -261,26 +309,32 @@ Firefox no soporta la instalación de PWA de forma nativa. Usa la extensión [PW
 
 ```
 exeviewer/
-├── index.html          # Página principal de la aplicación
-├── manifest.json       # Manifiesto PWA
-├── sw.js               # Service Worker
-├── server.js           # Servidor de desarrollo (Bun/Node.js)
-├── package.json        # Configuración del proyecto
+├── index.html              # Página principal de la aplicación
+├── manifest.json           # Manifiesto PWA
+├── sw.js                   # Service Worker
+├── server.js               # Servidor de desarrollo (Bun/Node.js)
+├── package.json            # Configuración del proyecto
+├── Dockerfile              # Definición de la imagen Docker
+├── nginx.conf              # Configuración de nginx para la imagen Docker
+├── docker-compose.yml      # Ejemplo de Docker Compose
+├── .env.dist            # Plantilla de variables de entorno para despliegues Docker
+├── docker/
+│   └── entrypoint.sh       # Genera js/config.js a partir de variables de entorno al arrancar
 ├── css/
-│   └── styles.css      # Estilos personalizados
+│   └── styles.css          # Estilos personalizados
 ├── js/
-│   ├── app.js          # Lógica principal de la aplicación
-│   ├── config.js       # Configuración del despliegue (sobreescribe los valores por defecto de app.js)
-│   ├── i18n.js         # Módulo de internacionalización
-│   └── zip.worker.js   # Web Worker para extracción ZIP
+│   ├── app.js              # Lógica principal de la aplicación
+│   ├── config.js           # Configuración del despliegue (sobreescribe los valores por defecto de app.js)
+│   ├── i18n.js             # Módulo de internacionalización
+│   └── zip.worker.js       # Web Worker para extracción ZIP
 ├── lang/
-│   ├── en.json         # Traducciones en inglés
-│   └── es.json         # Traducciones en español
-├── img/                # Iconos e imágenes
-├── vendor/             # Bibliotecas de terceros
-│   ├── bootstrap/      # Bootstrap 5.3.2
-│   ├── bootstrap-icons/# Bootstrap Icons 1.11.1
-│   └── fflate/         # fflate 0.8.2
+│   ├── en.json             # Traducciones en inglés
+│   └── es.json             # Traducciones en español
+├── img/                    # Iconos e imágenes
+├── vendor/                 # Bibliotecas de terceros
+│   ├── bootstrap/          # Bootstrap 5.3.2
+│   ├── bootstrap-icons/    # Bootstrap Icons 1.11.1
+│   └── fflate/             # fflate 0.8.2
 └── scripts/
     └── generate-icons.js   # Script de generación de iconos (requiere Node.js + sharp)
 ```

docker-compose.yml

@@ -0,0 +1,8 @@
+services:
+  exeviewer:
+    image: ghcr.io/exelearning/exeviewer:latest
+    ports:
+      - "8080:80"
+    env_file:
+      - .env
+    restart: unless-stopped

docker/entrypoint.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+set -e
+
+# Generate js/config.js from environment variables at container startup.
+# Any value not set in the environment keeps the application default (see js/app.js).
+cat > /usr/share/nginx/html/js/config.js <<EOF
+window.exeViewerConfig = {
+    gasProxyUrl: '${GAS_PROXY_URL:-}',
+    autoRestoreContent: ${AUTO_RESTORE_CONTENT:-true},
+    openExternalLinksInNewWindow: ${OPEN_EXTERNAL_LINKS_IN_NEW_WINDOW:-true},
+    validateExeContent: ${VALIDATE_EXE_CONTENT:-true},
+    allowDownloadByDefault: ${ALLOW_DOWNLOAD_BY_DEFAULT:-true}
+};
+EOF
+
+exec nginx -g 'daemon off;'