Merge branch 'develop' into endpoint-for-editing-catalogue-items-#9

.github/workflows/.ci.yml

@@ -91,3 +91,36 @@ jobs:
 
       - name: Run e2e tests
         run: DATABASE__NAME="test-ims" pytest test/e2e/ --cov
+
+  docker:
+    # This job triggers only if all the other jobs succeed and does different things depending on the context.
+    # The job builds the Docker image in all cases and also pushes the image to Harbor only if something is
+    # pushed to the develop branch.
+    needs: [linting, unit-tests, e2e-tests]
+    name: Docker
+    runs-on: ubuntu-latest
+    steps:
+    - name: Check out repo
+      uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0
+
+    - name: Login to Harbor
+      uses: docker/login-action@343f7c4344506bcbf9b4de18042ae17996df046d # v3.0.0
+      with:
+        registry: harbor.stfc.ac.uk/inventory-management-system
+        username: ${{ secrets.HARBOR_USERNAME }}
+        password: ${{ secrets.HARBOR_TOKEN }}
+
+    - name: Extract metadata (tags, labels) for Docker
+      id: meta
+      uses: docker/metadata-action@96383f45573cb7f253c731d3b3ab81c87ef81934 # v5.0.0
+      with:
+        images: harbor.stfc.ac.uk/inventory-management-system/ims-api
+
+    - name: ${{ github.event_name == 'push' && github.ref == 'refs/heads/develop' && 'Build and push Docker image to Harbor' || 'Build Docker image' }}
+      uses: docker/build-push-action@0565240e2d4ab88bba5387d719585280857ece09 # v5.0.0
+      with:
+        context: .
+        file: ./Dockerfile.prod
+        push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/develop' }}
+        tags: ${{ steps.meta.outputs.tags }}
+        labels: ${{ steps.meta.outputs.labels }}

Dockerfile.prod

@@ -0,0 +1,38 @@
+FROM python:3.10-alpine3.18
+
+WORKDIR /inventory-management-system-api-run
+
+COPY README.md pyproject.toml ./
+# Copy inventory_management_system_api source files
+COPY inventory_management_system_api/ inventory_management_system_api/
+
+RUN set -eux; \
+    \
+    # Install pip dependencies \
+    python -m pip install --no-cache-dir .; \
+    \
+    # Create loging.ini from its .example file \
+    cp inventory_management_system_api/logging.example.ini inventory_management_system_api/logging.ini; \
+    \
+    # Create a non-root user to run as \
+    addgroup -S inventory-management-system-api; \
+    adduser -S -D -G inventory-management-system-api -H -h /inventory-management-system-api-run inventory-management-system-api; \
+    \
+    # Create a log file \
+    touch inventory-management-system-api.log; \
+    # Change ownership of log file - app will need to write to it
+    chown -R inventory-management-system-api:inventory-management-system-api inventory-management-system-api.log;
+
+USER inventory-management-system-api
+
+ENV API__TITLE="Inventory Management System API"
+ENV API__DESCRIPTION="This is the API for the Inventory Management System"
+ENV DATABASE__PROTOCOL=mongodb
+ENV DATABASE__USERNAME=root
+ENV DATABASE__PASSWORD=example
+ENV DATABASE__HOSTNAME=localhost
+ENV DATABASE__PORT=27017
+ENV DATABASE__NAME=ims
+
+CMD ["uvicorn", "inventory_management_system_api.main:app", "--host", "0.0.0.0", "--port", "8000"]
+EXPOSE 8000

README.md

@@ -2,65 +2,80 @@
 
 ## How to Run
 
-This is a Python microservice created using FastAPI and requires a MongoDB instance to run against. If you are using
-Docker to run the application, the `docker-compose.yml file` has already been configured to start a MongoDB instance
-that can be accessed at `localhost:27017` using `root` as the username and `example` as the password.
+This is a Python microservice created using FastAPI and requires a MongoDB instance to run against.
 
 ### Prerequisites
 - Docker installed (if you want to run the microservice inside Docker)
 - Python 3.10 (or above) and MongoDB 6.0 installed on your machine if you are not using Docker
 - [MongoDB Compass](https://www.mongodb.com/products/compass) installed (if you want to interact with the database using a GUI)
+- This repository cloned
 
 ### Docker Setup
+The easiest way to run the application with Docker for local development is using the `docker-compose.yml` file. It is
+configured to spin up a MongoDB instance that can be accessed at `localhost:27017` using `root` as the username and
+`example` as the password. It also starts the application in a reload mode using the `Dockerfile`. Use the `Dockerfile`
+or `Dockerfile.prod` to run just the application itself in a container. The former is for local development  and must
+not be used in production.
 
-1. Ensure that Docker is installed and running on your machine.
-2. Clone the repository and navigate to the project directory:
-    ```bash
-    git clone [email protected]:ral-facilities/inventory-management-system-api.git
-    cd inventory-management-system-api
-3. Create a `logging.ini` file.
+Ensure that Docker is installed and running on your machine before proceeding.
+
+#### Using Docker Compose File
+1. Create a `logging.ini` file from the example in the root of the project directory:
     ```bash
    cp logging.example.ini logging.ini
     ```
 
-4. Build and start the Docker containers:
+2. Build and start the Docker containers:
     ```bash
    docker-compose up
     ```
-   The microservice should now be running inside Docker at http://localhost:8000. The Swagger UI can be accessed
-   at http://localhost:8000/docs.
+   The microservice should now be running inside Docker at http://localhost:8000 and its Swagger UI could be accessed
+   at http://localhost:8000/docs. A MongoDB instance should also be running at http://localhost:27017.
 
-### Local Setup
+#### Using Dockerfiles
+
+1. Build an image using either the `Dockerfile` or `Dockerfile.prod` from the root of the project directory:
+    ```bash
+   docker build -f Dockerfile.prod -t ims_api_image .
+    ```
 
-1. Clone the repository and navigate to the project directory:
+2. Start the container using the image built and map it to port `8000` locally:
     ```bash
-    git clone [email protected]:ral-facilities/inventory-management-system-api.git
-    cd inventory-management-system-api
+   docker run -p 8000:8000 --name ims_api_container ims_api_image
     ```
-2. Create a Python virtual environment and activate it:
+   or with values for the environment variables:
+    ```bash
+   docker run -p 8000:8000 --name ims_api_container --env DATABASE__NAME=test-ims ims_api_image
+    ```
+   The microservice should now be running inside Docker at http://localhost:8000 and its Swagger UI could be accessed
+   at http://localhost:8000/docs.
+
+### Local Setup
+
+Ensure that MongoDB is installed and running on your machine before proceeding.
+
+1. Create a Python virtual environment and activate it in the root of the project directory:
     ```bash
     python -m venv venv
     source venv/bin/activate
     ```
-3. Install the required dependencies using pip:
+2. Install the required dependencies using pip:
     ```bash
    pip install .[dev]
     ```
-4. Create a `.env` file using the `.env.example` file and modify the values inside accordingly.
-5. Create a `logging.ini` file using the `logging.example.ini` file and modify it accordingly.
-6. Ensure that MongoDB is running locally. If it's not installed, you can follow the official MongoDB installation guide
-   for your operating system.
-7. Start the microservice using Uvicorn from the project directory:
+3. Create a `.env` file using the `.env.example` file and modify the values inside accordingly.
+4. Create a `logging.ini` file using the `logging.example.ini` file and modify it accordingly.
+5. Start the microservice using Uvicorn:
     ```bash
    uvicorn inventory_management_system_api.main:app --log-config inventory_management_system_api/logging.ini --reload
     ```
    The microservice should now be running locally at http://localhost:8000. The Swagger UI can be accessed
    at http://localhost:8000/docs.
-8. To run the unit tests, run :
+6. To run the unit tests, run :
    ```bash
    pytest test/unit/
    ```
-9. To run the e2e tests, ensure that MongoDB is running locally and run:
+7. To run the e2e tests, run:
    ```bash
    DATABASE__NAME="test-ims" pytest test/e2e/
    ```