chore(containers): clarify Dockerfile comments and npm scripts usage in README

Author: nanotaboada

Dockerfile

@@ -1,6 +1,7 @@
-# - Stage 1: Builder -----------------------------------------------------------
-
+# ------------------------------------------------------------------------------
+# Stage 1: Builder
 # This stage builds the application and its dependencies.
+# ------------------------------------------------------------------------------
 FROM node:jod-alpine AS builder
 
 WORKDIR /app
@@ -24,9 +25,10 @@ RUN npm run build && \
     npm run swagger:docs && \
     npm prune --omit=dev
 
-# - Stage 2: Runtime -----------------------------------------------------------
-
+# ------------------------------------------------------------------------------
+# Stage 2: Runtime
 # This stage creates the final, minimal image to run the application.
+# ------------------------------------------------------------------------------
 FROM node:jod-alpine AS runtime
 
 WORKDIR /app
@@ -37,23 +39,21 @@ LABEL org.opencontainers.image.description="Proof of Concept for a RESTful API m
 LABEL org.opencontainers.image.licenses="MIT"
 LABEL org.opencontainers.image.source="https://github.com/nanotaboada/ts-node-samples-express-restful"
 
-# Install the SQLite runtime libraries, add a non-root user for security
-# hardening, and set the ownership of the /app directory to this user.
-RUN apk add --no-cache sqlite-libs && \
-    adduser -D -g "" express && \
-    chown -R express:express /app
+# Copy README and assets (read-only): often displayed in container registries such as Docker Hub or GHCR
+COPY --chown=root:root --chmod=644                          README.md                           ./
+COPY --chown=root:root --chmod=755                          assets/                             ./assets/
 
-# Copy transpiled JavaScript, pruned node_modules, SQLite database and Swagger JSON.
-COPY --from=builder --chown=express:express /app/dist ./dist
-COPY --from=builder --chown=express:express /app/node_modules ./dist/node_modules
-COPY --from=builder --chown=express:express /app/src/data/players-sqlite3.db ./dist/data/players-sqlite3.db
-COPY --from=builder --chown=express:express /app/dist/swagger.json ./dist/swagger.json
+# Install SQLite runtime libraries and create a system-like user (express) for running the app.
+RUN apk add --no-cache sqlite-libs && \
+    adduser -D -g "" express
 
-# Copy README and assets to the root of the app.
-# This is often displayed in registries like GitHub Container Registry.
-COPY README.md ./
-COPY assets/ ./assets/
+# Copy transpiled JavaScript, pruned node_modules, SQLite database and Swagger JSON, owned by express
+COPY --from=builder --chown=express:express --chmod=755     /app/dist                           ./dist
+COPY --from=builder --chown=express:express --chmod=755     /app/node_modules                   ./dist/node_modules
+COPY --from=builder --chown=express:express --chmod=644     /app/dist/swagger.json              ./dist/swagger.json
+COPY --from=builder --chown=express:express --chmod=664     /app/src/data/players-sqlite3.db    ./dist/data/players-sqlite3.db
 
+# Drop privileges: run as express
 USER express
 
 EXPOSE 9000

README.md

@@ -66,13 +66,13 @@ This project includes a multi-stage `Dockerfile` for local development and produ
 ### Build the image
 
 ```bash
-docker build -t ts-node-samples-express-restful .
+npm run docker:build
 ```
 
 ### Run the container
 
 ```bash
-docker run -p 9000:9000 ts-node-samples-express-restful:latest
+npm run docker:run
 ```
 
 ## Credits