Rosie Rhymes web deployment

An Angular 17 / Ionic 8 client application with bundled rhyme data, images and audio. The web deployment needs no API server, database or persistent volume. Capacitor's Android/iOS build and configuration remain separate.

Run with Docker

Install Docker with Linux container support and Docker Compose.

On Windows, start Docker Desktop first. If WSL or Virtual Machine Platform was just enabled, restart Windows before starting Docker Desktop. A newly installed Docker CLI may also require a new terminal window to pick up its PATH entry.

From this directory, run:

docker compose up --build -d

Open http://localhost:8080. Check status or logs with:

docker compose ps
docker compose logs -f web

Stop the service with docker compose down. Rebuild after code or asset changes with docker compose up --build -d.

Optional Compose variables can be set in your shell or a local .env file:

WEB_PORT=8080
SITE_URL=https://rosierhymes.com

WEB_PORT controls the host port; the container always listens on 8080. SITE_URL is a build-time HTTP(S) origin used in the sitemap and robots.txt. It must not include a subpath, query or fragment. Rebuild when changing it. The app is configured to live at the domain root (/).

Deploy an image

docker build --build-arg SITE_URL=https://rosierhymes.com -t rosie-rhymes:latest .
docker run -d --name rosie-rhymes --restart unless-stopped -p 8080:8080 rosie-rhymes:latest

For a managed container platform, push the image to your registry, configure container port 8080, and use GET /healthz for health checks. Terminate HTTPS at the platform's ingress or your reverse proxy and forward requests to port 8080. No runtime environment variables or secrets are required. If your platform uses a read-only filesystem, mount a writable temporary volume at /tmp, as the Compose configuration does.

The final image runs unprivileged Nginx and contains only the compiled web app. Nginx supports Angular deep links, audio byte-range requests, gzip compression, and long-lived caching for fingerprinted bundles. Entry HTML is revalidated; unhashed media is cached for one hour. Missing assets return 404.

Web build details

npm ci
npm run build:web

Use Node 20 for this Angular 17 project. See Angular's version compatibility table. The Docker build selects that version automatically; Node is absent from the runtime image. Angular 17 is an older, unsupported release, so a framework and build-toolchain upgrade should be planned separately from containerization.

The web command combines the existing optimized paid configuration with a web override and writes dist/web. It keeps the current full catalogue (Mode.PAID); this is not an access-controlled paid service. The existing demo configuration references missing TypeScript files and is not used by this container.

The web override omits the global rhyme scripts: these CommonJS data modules are already imported by RhymesService, and cannot execute as standalone browser scripts. The postbuild step generates deployment-specific metadata in dist/web without changing Capacitor's source manifest or dist/build output.

The existing buildPaid and buildDemo commands also run an SSH upload. The Docker build deliberately uses the separate build:web command, which only builds local files. It never runs an upload or a Capacitor sync/build.

The build context excludes native projects, node_modules, Git history, local environment files and design source files. Dependencies use npm ci and the committed lockfile. The runtime uses the official Nginx unprivileged image. Base image tags receive updates; pin them to digests in release pipelines if byte-for-byte repeatability is required.

Deployment checks

curl -I http://localhost:8080/
curl -I http://localhost:8080/rhyme/ABC-Song
curl http://localhost:8080/healthz
curl -I http://localhost:8080/assets/missing.mp3

Expect 200 for the app and deep link, ok for the health check, and 404 for the missing asset. Open a rhyme in a browser and verify audio playback and seeking.

Validation during setup: the production web build, Docker Compose configuration, Nginx syntax, HTTP routing/cache/gzip/audio-range checks, deployment metadata, and browser navigation/refresh checks passed. Nginx HTTP checks used a temporary Windows Nginx instance with the deployment configuration (local root and port). The Linux image build and container startup still need verification after the Windows restart required by Docker's newly enabled WSL dependencies.