From 8622496be065cf1959ca57c9bee2071a8f298064 Mon Sep 17 00:00:00 2001 From: gsayer Date: Tue, 8 Jul 2025 20:57:18 +0200 Subject: [PATCH 01/10] feat(docker): add docker-compose stack and documentation --- README.md | 61 +++++++++++++++++++++++++++++++++++++++++ docker-compose.yml | 67 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 docker-compose.yml diff --git a/README.md b/README.md index 4c80265..901896e 100644 --- a/README.md +++ b/README.md @@ -12,3 +12,64 @@ | :point_right: **[Welcome to the Payroll Engine, please continue to the Wiki](https://github.com/Payroll-Engine/PayrollEngine/wiki)** | |:------------------------| + +# Payroll Engine Docker Stack + +This document describes how to set up and run the Payroll Engine stack using Docker. + +## Prerequisites + +- Docker +- Docker Compose + +## Getting Started + +### 1. Environment Configuration + +The application uses a `.env` file to manage the database password. This file must be created in the same directory as the `docker-compose.yml` file (`PayrollEngine/`). + +Create a file named `.env` with the following content: + +``` +# Default database password +# Please change this to a strong password in your local environment +DB_PASSWORD=YourStrong!Password123 +``` + +**Important:** Replace `YourStrong!Password123` with a secure password of your choice. + +### 2. Build and Run the Stack + +To build and start all the services, run the following command from the `PayrollEngine/` directory: + +```sh +docker-compose up --build +``` + +This command will: +- Build the Docker images for the `backend-api`, `webapp`, and `db-init` services. +- Start all the services in the correct order. +- Initialize the database. + +### 3. Accessing the Applications + +Once the stack is running, you can access the following services: + +- **PayrollEngine WebApp**: `http://localhost:8081` +- **PayrollEngine Backend API**: `http://localhost:5001` (HTTP) or `https://localhost:5002` (HTTPS) +- **SQL Server Database**: Connect using a client on `localhost:1433` with the `sa` user and the password you defined in the `.env` file. + +### 4. Stopping the Stack + +To stop the services, press `Ctrl+C` in the terminal where `docker-compose up` is running. + +To stop and remove the containers, run: + +```sh +docker-compose down +``` + +To remove the database volume as well, run: +```sh +docker-compose down -v +``` diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..05b6702 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,67 @@ +version: '3.8' + +services: + db: + image: mcr.microsoft.com/mssql/server:2022-latest + container_name: payroll-db + environment: + ACCEPT_EULA: 'Y' + MSSQL_SA_PASSWORD: '${DB_PASSWORD}' + ports: + - "1433:1433" + volumes: + - mssql-data:/var/opt/mssql + + db-init: + build: + context: ../PayrollEngine.SqlServer.DbQuery + dockerfile: Dockerfile + depends_on: + db: + condition: service_started + environment: + DB_CONNECTION_STRING: 'Server=db;Database=master;User Id=sa;Password=${DB_PASSWORD};TrustServerCertificate=True' + command: > + /bin/sh -c " + echo 'Waiting for database to be ready...' + sleep 15 + echo 'Executing SQL script...' + dotnet PayrollEngine.SqlServer.DbQuery.dll query -c \"${DB_CONNECTION_STRING}\" -f /sql/ModelCreate.sql + " + volumes: + - ../PayrollEngine.Backend/Database/ModelCreate.sql:/sql/ModelCreate.sql:ro + + backend-api: + build: + context: ../PayrollEngine.Backend + dockerfile: Dockerfile + container_name: payroll-backend-api + ports: + - "5001:8080" + - "5002:8081" + environment: + ASPNETCORE_URLS: 'http://+:8080;https://+:8081' + ConnectionStrings__PayrollDatabaseConnection: 'Server=db;Database=PayrollEngine;User Id=sa;Password=${DB_PASSWORD};TrustServerCertificate=True;' + depends_on: + - db-init + volumes: + - ../PayrollEngine.Backend/logs:/app/logs + + webapp: + build: + context: ../PayrollEngine.WebApp + dockerfile: Dockerfile + container_name: payroll-webapp + ports: + - "8081:8080" + - "8082:8081" + environment: + ASPNETCORE_URLS: 'http://+:8080;https://+:8081' + ApiSettings__BaseUrl: 'http://backend-api:8080' + depends_on: + - backend-api + volumes: + - ../PayrollEngine.WebApp/logs:/app/logs + +volumes: + mssql-data: \ No newline at end of file From 4719ad0d66a7d9054ca60fa7f160164cc1dd8f60 Mon Sep 17 00:00:00 2001 From: gsayer Date: Tue, 8 Jul 2025 22:11:07 +0200 Subject: [PATCH 02/10] feat(docker): Configure docker-compose for local development --- docker-compose.yml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index 05b6702..1a7a2eb 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,5 +1,3 @@ -version: '3.8' - services: db: image: mcr.microsoft.com/mssql/server:2022-latest @@ -21,12 +19,13 @@ services: condition: service_started environment: DB_CONNECTION_STRING: 'Server=db;Database=master;User Id=sa;Password=${DB_PASSWORD};TrustServerCertificate=True' + entrypoint: /bin/sh command: > - /bin/sh -c " + -c " echo 'Waiting for database to be ready...' sleep 15 echo 'Executing SQL script...' - dotnet PayrollEngine.SqlServer.DbQuery.dll query -c \"${DB_CONNECTION_STRING}\" -f /sql/ModelCreate.sql + dotnet PayrollEngine.SqlServer.DbQuery.dll query /sql/ModelCreate.sql '${DB_CONNECTION_STRING}' " volumes: - ../PayrollEngine.Backend/Database/ModelCreate.sql:/sql/ModelCreate.sql:ro From 1f8d75dabd8ae0460b4bf03cbce6a39f242c9d5f Mon Sep 17 00:00:00 2001 From: gsayer Date: Wed, 9 Jul 2025 03:30:17 +0200 Subject: [PATCH 03/10] feat: Improve Docker stack configuration and database initialization - Replace custom DbQuery tool with standard sqlcmd for database initialization - Use mcr.microsoft.com/mssql-tools image for more reliable db-init service - Configure services to use HTTP only (remove HTTPS to avoid certificate issues) - Add restart policy for webapp service - Add .env file with database password configuration - Improve service dependencies and startup order --- .env | 1 + docker-compose.yml | 29 +++++++++++++++-------------- 2 files changed, 16 insertions(+), 14 deletions(-) create mode 100644 .env diff --git a/.env b/.env new file mode 100644 index 0000000..6190c61 --- /dev/null +++ b/.env @@ -0,0 +1 @@ +DB_PASSWORD='SuperSecretP@ssword!' \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml index 1a7a2eb..3033de7 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -11,21 +11,20 @@ services: - mssql-data:/var/opt/mssql db-init: - build: - context: ../PayrollEngine.SqlServer.DbQuery - dockerfile: Dockerfile + image: mcr.microsoft.com/mssql-tools + container_name: payrollengine-db-init depends_on: - db: - condition: service_started - environment: - DB_CONNECTION_STRING: 'Server=db;Database=master;User Id=sa;Password=${DB_PASSWORD};TrustServerCertificate=True' + - db entrypoint: /bin/sh command: > -c " echo 'Waiting for database to be ready...' - sleep 15 + sleep 20 + echo 'Creating database...' + /opt/mssql-tools/bin/sqlcmd -S db -U sa -P \"${DB_PASSWORD}\" -C -Q \"IF NOT EXISTS (SELECT name FROM sys.databases WHERE name = 'PayrollEngine') CREATE DATABASE PayrollEngine\" echo 'Executing SQL script...' - dotnet PayrollEngine.SqlServer.DbQuery.dll query /sql/ModelCreate.sql '${DB_CONNECTION_STRING}' + /opt/mssql-tools/bin/sqlcmd -S db -U sa -P \"${DB_PASSWORD}\" -C -d PayrollEngine -i /sql/ModelCreate.sql + echo 'Database initialization completed.' " volumes: - ../PayrollEngine.Backend/Database/ModelCreate.sql:/sql/ModelCreate.sql:ro @@ -37,12 +36,13 @@ services: container_name: payroll-backend-api ports: - "5001:8080" - - "5002:8081" environment: - ASPNETCORE_URLS: 'http://+:8080;https://+:8081' + ASPNETCORE_URLS: 'http://+:8080' + ASPNETCORE_ENVIRONMENT: 'Development' ConnectionStrings__PayrollDatabaseConnection: 'Server=db;Database=PayrollEngine;User Id=sa;Password=${DB_PASSWORD};TrustServerCertificate=True;' depends_on: - - db-init + db-init: + condition: service_completed_successfully volumes: - ../PayrollEngine.Backend/logs:/app/logs @@ -53,12 +53,13 @@ services: container_name: payroll-webapp ports: - "8081:8080" - - "8082:8081" environment: - ASPNETCORE_URLS: 'http://+:8080;https://+:8081' + ASPNETCORE_URLS: 'http://+:8080' + ASPNETCORE_ENVIRONMENT: 'Development' ApiSettings__BaseUrl: 'http://backend-api:8080' depends_on: - backend-api + restart: unless-stopped volumes: - ../PayrollEngine.WebApp/logs:/app/logs From 710d8cc949ba71fc536c7510cadc881431119166 Mon Sep 17 00:00:00 2001 From: gsayer Date: Wed, 9 Jul 2025 18:58:26 +0200 Subject: [PATCH 04/10] Add Docker documentation and update .gitignore --- .gitignore | 3 +++ DOCKER.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 63 insertions(+) create mode 100644 DOCKER.md diff --git a/.gitignore b/.gitignore index d9424e7..f9b40b2 100644 --- a/.gitignore +++ b/.gitignore @@ -348,3 +348,6 @@ ASALocalRun/ /**/bin/ /**/obj/ _site + +# Environment variables file for local development +.env \ No newline at end of file diff --git a/DOCKER.md b/DOCKER.md new file mode 100644 index 0000000..a18fc5d --- /dev/null +++ b/DOCKER.md @@ -0,0 +1,60 @@ +# Payroll Engine Docker Stack + +This document describes how to set up and run the Payroll Engine stack using Docker. + +## Prerequisites + +- Docker +- Docker Compose + +## Getting Started + +### 1. Environment Configuration + +The application uses a `.env` file to manage the database password. This file must be created in the same directory as the `docker-compose.yml` file (`PayrollEngine/`). + +Create a file named `.env` with the following content: + +``` +# Default database password +# Please change this to a strong password in your local environment +DB_PASSWORD=YourStrong!Password123 +``` + +**Important:** Replace `YourStrong!Password123` with a secure password of your choice. + +### 2. Build and Run the Stack + +To build and start all the services, run the following command from the `PayrollEngine/` directory: + +```sh +docker-compose up --build +``` + +This command will: +- Build the Docker images for the `backend-api`, `webapp`, and `db-init` services. +- Start all the services in the correct order. +- Initialize the database. + +### 3. Accessing the Applications + +Once the stack is running, you can access the following services: + +- **PayrollEngine WebApp**: `http://localhost:8081` +- **PayrollEngine Backend API**: `http://localhost:5001` (HTTP) or `https://localhost:5002` (HTTPS) +- **SQL Server Database**: Connect using a client on `localhost:1433` with the `sa` user and the password you defined in the `.env` file. + +### 4. Stopping the Stack + +To stop the services, press `Ctrl+C` in the terminal where `docker-compose up` is running. + +To stop and remove the containers, run: + +```sh +docker-compose down +``` + +To remove the database volume as well, run: +```sh +docker-compose down -v +``` From 50193218ebc1636aeb494249b15ab013ab3497ab Mon Sep 17 00:00:00 2001 From: Guillaume Date: Wed, 9 Jul 2025 19:00:38 +0200 Subject: [PATCH 05/10] Delete .env --- .env | 1 - 1 file changed, 1 deletion(-) delete mode 100644 .env diff --git a/.env b/.env deleted file mode 100644 index 6190c61..0000000 --- a/.env +++ /dev/null @@ -1 +0,0 @@ -DB_PASSWORD='SuperSecretP@ssword!' \ No newline at end of file From 594d97c5c768a5909547a0a890592218d11fd8df Mon Sep 17 00:00:00 2001 From: Guillaume Date: Wed, 9 Jul 2025 19:15:19 +0200 Subject: [PATCH 06/10] Update README.md remove Docker doc > Docker.md --- README.md | 61 ------------------------------------------------------- 1 file changed, 61 deletions(-) diff --git a/README.md b/README.md index 901896e..4c80265 100644 --- a/README.md +++ b/README.md @@ -12,64 +12,3 @@ | :point_right: **[Welcome to the Payroll Engine, please continue to the Wiki](https://github.com/Payroll-Engine/PayrollEngine/wiki)** | |:------------------------| - -# Payroll Engine Docker Stack - -This document describes how to set up and run the Payroll Engine stack using Docker. - -## Prerequisites - -- Docker -- Docker Compose - -## Getting Started - -### 1. Environment Configuration - -The application uses a `.env` file to manage the database password. This file must be created in the same directory as the `docker-compose.yml` file (`PayrollEngine/`). - -Create a file named `.env` with the following content: - -``` -# Default database password -# Please change this to a strong password in your local environment -DB_PASSWORD=YourStrong!Password123 -``` - -**Important:** Replace `YourStrong!Password123` with a secure password of your choice. - -### 2. Build and Run the Stack - -To build and start all the services, run the following command from the `PayrollEngine/` directory: - -```sh -docker-compose up --build -``` - -This command will: -- Build the Docker images for the `backend-api`, `webapp`, and `db-init` services. -- Start all the services in the correct order. -- Initialize the database. - -### 3. Accessing the Applications - -Once the stack is running, you can access the following services: - -- **PayrollEngine WebApp**: `http://localhost:8081` -- **PayrollEngine Backend API**: `http://localhost:5001` (HTTP) or `https://localhost:5002` (HTTPS) -- **SQL Server Database**: Connect using a client on `localhost:1433` with the `sa` user and the password you defined in the `.env` file. - -### 4. Stopping the Stack - -To stop the services, press `Ctrl+C` in the terminal where `docker-compose up` is running. - -To stop and remove the containers, run: - -```sh -docker-compose down -``` - -To remove the database volume as well, run: -```sh -docker-compose down -v -``` From da25998b36592042fc782269d7a24b6bd226ea25 Mon Sep 17 00:00:00 2001 From: gsayer Date: Sun, 13 Jul 2025 21:03:55 +0200 Subject: [PATCH 07/10] fix: add multi-platform support for SQL Server containers - Force linux/amd64 platform for SQL Server and SQL Tools containers - Improves database connection reliability across different architectures - Adds connection test before database initialization - Addresses cross-platform issues reported in PayrollEngine/PayrollEngine#2 --- docker-compose.yml | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index 3033de7..ac0c4ae 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,6 +1,7 @@ services: db: image: mcr.microsoft.com/mssql/server:2022-latest + platform: linux/amd64 # Force x86_64 for compatibility across platforms container_name: payroll-db environment: ACCEPT_EULA: 'Y' @@ -12,6 +13,7 @@ services: db-init: image: mcr.microsoft.com/mssql-tools + platform: linux/amd64 # Force x86_64 for compatibility container_name: payrollengine-db-init depends_on: - db @@ -19,7 +21,9 @@ services: command: > -c " echo 'Waiting for database to be ready...' - sleep 20 + sleep 30 + echo 'Testing database connection...' + /opt/mssql-tools/bin/sqlcmd -S db -U sa -P \"${DB_PASSWORD}\" -C -Q \"SELECT @@VERSION\" || { echo 'Database connection failed'; exit 1; } echo 'Creating database...' /opt/mssql-tools/bin/sqlcmd -S db -U sa -P \"${DB_PASSWORD}\" -C -Q \"IF NOT EXISTS (SELECT name FROM sys.databases WHERE name = 'PayrollEngine') CREATE DATABASE PayrollEngine\" echo 'Executing SQL script...' @@ -33,6 +37,9 @@ services: build: context: ../PayrollEngine.Backend dockerfile: Dockerfile + platforms: + - linux/amd64 + - linux/arm64 container_name: payroll-backend-api ports: - "5001:8080" @@ -50,6 +57,9 @@ services: build: context: ../PayrollEngine.WebApp dockerfile: Dockerfile + platforms: + - linux/amd64 + - linux/arm64 container_name: payroll-webapp ports: - "8081:8080" @@ -64,4 +74,4 @@ services: - ../PayrollEngine.WebApp/logs:/app/logs volumes: - mssql-data: \ No newline at end of file + mssql-data: \ No newline at end of file From ad6f9531e7a36cdf77f947344bb309a01d9154fe Mon Sep 17 00:00:00 2001 From: gsayer Date: Mon, 14 Jul 2025 02:30:23 +0200 Subject: [PATCH 08/10] fix: resolve SA database connection authentication issues - Update docker-compose.yml to use SQL Server 2022 compatible tools - Replace obsolete mssql-tools with mssql/server:2022-latest image - Update all sqlcmd references to sqlcmd18 for SQL Server 2022 compatibility - Add MSSQL_PID=Developer environment variable for proper configuration - Force platform: linux/amd64 for cross-platform compatibility Resolves GitHub discussion #2 point 1: SA login authentication failures --- docker-compose.yml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index ac0c4ae..048503b 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -6,13 +6,14 @@ services: environment: ACCEPT_EULA: 'Y' MSSQL_SA_PASSWORD: '${DB_PASSWORD}' + MSSQL_PID: 'Developer' ports: - "1433:1433" volumes: - mssql-data:/var/opt/mssql db-init: - image: mcr.microsoft.com/mssql-tools + image: mcr.microsoft.com/mssql/server:2022-latest platform: linux/amd64 # Force x86_64 for compatibility container_name: payrollengine-db-init depends_on: @@ -23,11 +24,11 @@ services: echo 'Waiting for database to be ready...' sleep 30 echo 'Testing database connection...' - /opt/mssql-tools/bin/sqlcmd -S db -U sa -P \"${DB_PASSWORD}\" -C -Q \"SELECT @@VERSION\" || { echo 'Database connection failed'; exit 1; } + /opt/mssql-tools18/bin/sqlcmd -S db -U sa -P \"${DB_PASSWORD}\" -C -Q \"SELECT @@VERSION\" || { echo 'Database connection failed'; exit 1; } echo 'Creating database...' - /opt/mssql-tools/bin/sqlcmd -S db -U sa -P \"${DB_PASSWORD}\" -C -Q \"IF NOT EXISTS (SELECT name FROM sys.databases WHERE name = 'PayrollEngine') CREATE DATABASE PayrollEngine\" + /opt/mssql-tools18/bin/sqlcmd -S db -U sa -P \"${DB_PASSWORD}\" -C -Q \"IF NOT EXISTS (SELECT name FROM sys.databases WHERE name = 'PayrollEngine') CREATE DATABASE PayrollEngine\" echo 'Executing SQL script...' - /opt/mssql-tools/bin/sqlcmd -S db -U sa -P \"${DB_PASSWORD}\" -C -d PayrollEngine -i /sql/ModelCreate.sql + /opt/mssql-tools18/bin/sqlcmd -S db -U sa -P \"${DB_PASSWORD}\" -C -d PayrollEngine -i /sql/ModelCreate.sql echo 'Database initialization completed.' " volumes: From c2f25b183c8847c6a98ed8371962a7ad3ca61fdf Mon Sep 17 00:00:00 2001 From: gsayer Date: Wed, 16 Jul 2025 00:53:18 +0200 Subject: [PATCH 09/10] Update DOCKER.md with password requirements and troubleshooting - Add password requirements to avoid special characters - Document alphanumeric-only password policy - Include SQL Server connection verification command - Address authentication issues that appear as 'sqlcmd not found' errors Resolves authentication failures caused by special characters in passwords that were reported in GitHub Discussion #2. --- DOCKER.md | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/DOCKER.md b/DOCKER.md index a18fc5d..14901a9 100644 --- a/DOCKER.md +++ b/DOCKER.md @@ -16,12 +16,16 @@ The application uses a `.env` file to manage the database password. This file mu Create a file named `.env` with the following content: ``` -# Default database password -# Please change this to a strong password in your local environment -DB_PASSWORD=YourStrong!Password123 +# PayrollEngine Docker Stack Configuration +DB_PASSWORD=PayrollStrongPass789 ``` -**Important:** Replace `YourStrong!Password123` with a secure password of your choice. +**Important Password Requirements:** +- Use **alphanumeric characters only** (letters and numbers) +- **Avoid special characters** like `!`, `@`, `#`, `$`, etc. +- Special characters can cause authentication failures that appear as misleading "sqlcmd not found" errors +- Example of good password: `PayrollStrongPass789` +- Example of problematic password: `PayrollStrongPass789!` (contains `!`) ### 2. Build and Run the Stack @@ -43,6 +47,10 @@ Once the stack is running, you can access the following services: - **PayrollEngine WebApp**: `http://localhost:8081` - **PayrollEngine Backend API**: `http://localhost:5001` (HTTP) or `https://localhost:5002` (HTTPS) - **SQL Server Database**: Connect using a client on `localhost:1433` with the `sa` user and the password you defined in the `.env` file. +- **Verification:** : Test the SQL Server connection: +```sh +docker exec payroll-db /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourPassword" -C -Q "SELECT @@VERSION" +``` ### 4. Stopping the Stack @@ -58,3 +66,10 @@ To remove the database volume as well, run: ```sh docker-compose down -v ``` + + + **Verification:** + Test the SQL Server connection: +```sh +docker exec payroll-db /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -P "YourPassword" -C -Q "SELECT @@VERSION" +``` \ No newline at end of file From 2faf6875ccd04d3184bf2a58c0f0898bff51617f Mon Sep 17 00:00:00 2001 From: gsayer Date: Wed, 16 Jul 2025 02:08:59 +0200 Subject: [PATCH 10/10] Force linux/amd64 architecture - avoid unsupported option: 'platforms' --- docker-compose.yml | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docker-compose.yml b/docker-compose.yml index 048503b..ced2756 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -38,9 +38,7 @@ services: build: context: ../PayrollEngine.Backend dockerfile: Dockerfile - platforms: - - linux/amd64 - - linux/arm64 + platform: linux/amd64 container_name: payroll-backend-api ports: - "5001:8080" @@ -58,9 +56,7 @@ services: build: context: ../PayrollEngine.WebApp dockerfile: Dockerfile - platforms: - - linux/amd64 - - linux/arm64 + platform: linux/amd64 container_name: payroll-webapp ports: - "8081:8080"