README: Part 1 - Developing a REST Web Service

This document describes how to set up and use the REST Web Service. The service retrieves population data for Luxembourg from a Statec API and returns it in JSON format.

---

1. Setup Instructions

1.1 Prerequisites

Ensure you have the following installed:

• Node.js (v18 or higher)
• npm (Node Package Manager)

1.2 Install Dependencies

Clone the repository and navigate to the project directory. Then, install the required dependencies:

npm install

---

2. Running the Application

2.1 Start the Server

Run the following command to start the server:

npm start

By default, the server runs on port 3000.

2.2 Access the Web Service

The base URL of the service is:

http://localhost:3000

---

3. Endpoints

3.1 Get Population Data

Endpoint:

GET /population/:year

Description:
Fetches the total population, male population (Luxembourgish and foreign), and female population (Luxembourgish and foreign) for the specified year.

Parameters:

• :year (path parameter): The year for which the population data is requested.

Example Request:

GET http://localhost:3000/population/2020

Example Response:

{
  "totalPopulation": 634000,
  "malePopulation": {
    "total": 317000,
    "luxembourgish": 200000,
    "foreign": 117000
  },
  "femalePopulation": {
    "total": 317000,
    "luxembourgish": 200000,
    "foreign": 117000
  }
}

---

4. Error Handling

4.1 Invalid Year

If the requested year does not exist in the dataset, the service returns population data for the nearest years (before and after).

Example Request:

GET http://localhost:3000/population/1825

Example Response:

{
  "error": "No data found for year 1825. Closest year before: 1821. Closest year after: 1839.",
  "closestYears": {
    "closestYearBefore": 1821,
    "closestYearAfter": 1839
  }
}

4.2 Invalid Input

If the input year is invalid (e.g., not a number), the service responds with a 400 Bad Request.

Example Response:

{
  "error": "Invalid year"
}

---

5. Code Overview

Key Files:

• src/server.js: Main application file that handles routes and logic.
• src/populationService.js: Contains logic to fetch and process population data from the Statec API.

---

6. Example Usage

1. Start the server:

   npm start

2. Use curl or a browser to test the endpoint:

   curl http://localhost:3000/population/2020

3. View the JSON response with population data.

README: Part 2 - Running the Application with Docker

This document explains how to build and run the REST Web Service using Docker.

---

1. Dockerfile Overview

The Dockerfile is divided into two stages:

1. Build Stage:

   • Installs dependencies and copies the source code.
   • Prepares the application for production.

2. Production Stage:

   • Creates a lightweight container with only the necessary files and dependencies.
   • Sets the working directory and starts the application.

---

2. Prerequisites

Ensure you have the following installed:

• Docker (v20.10 or higher)

---

3. Building the Docker Image

Run the following command to build the Docker image:

docker build -t population-server .

This command:

• Pulls the Node.js 18 Alpine base image.
• Copies the application code and dependencies into the container.
• Produces a minimal production-ready image.

---

4. Running the Docker Container

Run the container using:

docker run -p 3000:3000 population-server

This command:

• Maps port 3000 of the container to port 3000 on your host machine.
• Starts the server.

---

5. Accessing the Web Service

Once the container is running, you can access the service at:

http://localhost:3000

---

6. Example Access URL

After running the container:

http://localhost:3000/population/<year>

Example:

http://localhost:3000/population/2020

---

7. Stopping the Container

To stop the container, find the container's ID:

docker ps

Then stop it using:

docker stop <container-id>

Part 3: Deploying the Application Using Kubernetes with Minikube

This guide explains how to deploy the Population Server application on a local Kubernetes cluster using Minikube. The deployment will create two replicas of the application and expose it as a LoadBalancer service for access.

Example video: https://drive.google.com/file/d/1y57Wl_e5sOPEpgIaeaeV3WKgWyA0qXQU/view?usp=sharing

---

Prerequisites

• Minikube installed and configured.
• kubectl command-line tool installed.
• Docker is installed and running.

---

Steps to Deploy

1. Start Minikube

1. Launch Minikube:

   minikube start

2. Verify Minikube is running:

   minikube status

---

2. Build the Docker Image Inside Minikube

Minikube uses its own Docker environment, so you need to build the image there:

1. Set up Docker to use Minikube’s environment:

   & minikube -p minikube docker-env | Invoke-Expression

2. Build the Docker image:

   docker build -t population-server:latest .

3. Confirm the image is available in Minikube:

   docker images

---

3. Apply the Kubernetes Deployment and Service

1. Use the provided deployment.yaml file to create the Deployment and service.yaml for Service:

   kubectl apply -f deployment.yaml
   kubectl apply -f service.yaml

2. Verify that the pods are running:

   kubectl get pods

   Example output:

   NAME                                  READY   STATUS    RESTARTS   AGE
   population-server-<random-uid>       1/1     Running   0          2m
   population-server-<random-uid>       1/1     Running   0          2m
   

3. Check the Deployment and Service status:

   kubectl get deployments
   kubectl get services

---

4. Access the Application

1. Get the URL for the LoadBalancer service:

   minikube service population-server --url

2. Open the returned URL in your browser or test it using curl:

   curl <minikube-service-url>

---

5. Turn Off the Minikube Cluster

When you’re done with the cluster, you can stop and delete Minikube to save resources:

1. Stop the Minikube cluster:

   minikube stop

2. Delete the cluster:

   minikube delete

---