Docker documentation

Author: hansipie

Diff for: Dockerfile

@@ -1,35 +1,53 @@
-####################################################
-# build stage
-####################################################
+# ---------------------------------------------------
+# Build Stage
+# ---------------------------------------------------
 
+# Use Alpine Linux 3.18 as the base image for the build stage
 FROM alpine:3.18 AS build
+
+# Update package list and install build dependencies
 RUN apk update && \
     apk add --no-cache \
     build-base zlib-dev
-    
+
+# Set the working directory inside the container
 WORKDIR /civetweb
+
+# Copy source code and other necessary files into the container
 COPY src ./src/
 COPY include ./include/
 COPY Makefile ./
 COPY resources ./resources/
 COPY *.md ./
 
+# Build Civetweb with all features and install it into /app directory
 RUN make build && \
     make WITH_ALL=1 && \
     make install PREFIX=/app
 
-####################################################
-# image stage
-####################################################
+# ---------------------------------------------------
+# Image Stage
+# ---------------------------------------------------
 
+# Use Alpine Linux 3.18 as the base image for the final stage
 FROM alpine:3.18
+
+# Update package list and install runtime dependencies
 RUN apk update && \
     apk add --no-cache \
     libstdc++ zlib
 
+# Create a non-root user and group for running Civetweb
 RUN addgroup -S civetweb && adduser -S civetweb -G civetweb
+
+# Switch to the non-root user
 USER civetweb
 
+# Copy the built application from the build stage into this stage
 COPY --chown=civetweb:civetweb --from=build /app/ /app/
 
+# Expose port 8080 for the application
+EXPOSE 8080
+
+# Set the entry point for the container
 ENTRYPOINT  [ "/app/bin/civetweb", "/app/etc/civetweb.conf" ]

Diff for: README.md

@@ -75,6 +75,7 @@ Quick start documentation
 - [docs/Building.md](https://github.com/civetweb/civetweb/blob/master/docs/Building.md) - Building the Server (quick start guide)
 - [docs/Embedding.md](https://github.com/civetweb/civetweb/blob/master/docs/Embedding.md) - Embedding (how to add HTTP support to an existing application)
 - [docs/OpenSSL.md](https://github.com/civetweb/civetweb/blob/master/docs/OpenSSL.md) - Adding HTTPS (SSL/TLS) support using OpenSSL.
+- [docs/Docker.md](https://github.com/civetweb/civetweb/blob/master/docs/Docker.md) - Use civetweb in a Docker container.
 - [API documentation](https://github.com/civetweb/civetweb/tree/master/docs/api) - Additional documentation on the civetweb application programming interface ([civetweb.h](https://github.com/civetweb/civetweb/blob/master/include/civetweb.h)).
 - [RELEASE_NOTES.md](https://github.com/civetweb/civetweb/blob/master/RELEASE_NOTES.md) - Release Notes
 - [SECURITY.md](https://github.com/civetweb/civetweb/blob/master/SECURITY.md) - Security Policy

Diff for: docs/Docker.md

@@ -0,0 +1,96 @@
+# Running Civetweb in Docker
+
+## Overview
+
+This guide explains how to build and run Civetweb using a multi-stage Dockerfile. The Dockerfile uses Alpine Linux for both the build and runtime stages, making the final image lightweight.
+
+## Prerequisites
+
+- Docker installed on your machine
+- Basic understanding of Docker commands
+
+## Dockerfile Explained
+
+### Build Stage
+
+The build stage uses Alpine Linux 3.18 and installs the necessary build tools and libraries.
+
+```Dockerfile
+FROM alpine:3.18 AS build
+RUN apk update && \
+    apk add --no-cache \
+    build-base zlib-dev
+```
+
+The source code and other necessary files are copied into the `/civetweb` directory in the container.
+
+```Dockerfile
+WORKDIR /civetweb
+COPY src ./src/
+COPY include ./include/
+COPY Makefile ./
+COPY resources ./resources/
+COPY *.md ./
+```
+
+The Civetweb server is then built and installed into the `/app` directory.
+
+```Dockerfile
+RUN make build && \
+    make WITH_ALL=1 && \
+    make install PREFIX=/app
+```
+
+### Image Stage
+
+The image stage also uses Alpine Linux 3.18 but installs only the runtime dependencies.
+
+```Dockerfile
+FROM alpine:3.18
+RUN apk update && \
+    apk add --no-cache \
+    libstdc++ zlib
+```
+
+A non-root user `civetweb` is created for security reasons.
+
+```Dockerfile
+RUN addgroup -S civetweb && adduser -S civetweb -G civetweb
+USER civetweb
+```
+
+The built application from the build stage is copied into this stage.
+
+```Dockerfile
+COPY --chown=civetweb:civetweb --from=build /app/ /app/
+```
+
+The container will listen on port 8080 at runtime.
+
+```Dockerfile
+EXPOSE 8080
+```
+
+Finally, the entry point for the container is set.
+
+```Dockerfile
+ENTRYPOINT  [ "/app/bin/civetweb", "/app/etc/civetweb.conf" ]
+```
+
+## Build and Run
+
+To build the Docker image, run:
+
+```bash
+docker build -t civetweb:latest .
+```
+
+To run the container, execute:
+
+```bash
+docker run -p 8080:8080 civetweb:latest
+```
+
+## Conclusion
+
+This Dockerfile provides a secure and efficient way to build and run Civetweb. The use of multi-stage builds ensures that the final image is as small as possible. The `EXPOSE` directive informs that the application will listen on port 8080, making it easier to map ports when running the container.