148 lines
4.9 KiB
Markdown
148 lines
4.9 KiB
Markdown
# GiecChallenge
|
||
|
||
A full‑stack demo application consisting of an ASP.NET Core backend and a React frontend.
|
||
The project is container‑based and can be run locally with Docker‑Compose or built and deployed through GitLab CI.
|
||
|
||
## Table of Contents
|
||
- [Overview](#overview)
|
||
- [Prerequisites](#prerequisites)
|
||
- [Environment Variables](#environment-variables)
|
||
- [Running Locally](#running-locally)
|
||
- [Building & Testing](#building--testing)
|
||
- [Deploying with GitLab CI](#deploying-with-gitlab-ci)
|
||
- [Project Structure](#project-structure)
|
||
- [License](#license)
|
||
|
||
---
|
||
|
||
### Overview
|
||
- **Backend**: ASP.NET Core 10.0 API (`backend/GiecChallenge`).
|
||
Handles authentication, JWT generation, and CRUD operations for products, purchases, etc.
|
||
- **Frontend**: React (create‑react‑app) (`frontend`).
|
||
Consumes the API and provides a UI for managing data.
|
||
- **Infrastructure**: Docker containers for backend, frontend, and PostgreSQL database, orchestrated with `docker‑compose.yml`.
|
||
|
||
All secrets (DB credentials, JWT secret, passwords, etc.) are externalised to environment variables and **never** committed to source control.
|
||
|
||
---
|
||
|
||
### Prerequisites
|
||
- Docker Engine (>= 20.10) with Docker‑Compose support
|
||
- Git (to clone the repository)
|
||
- (Optional) GitLab Runner with Docker‑in‑Docker for CI pipelines
|
||
- Node 14+ (for local frontend development)
|
||
- .NET 10 SDK (for local backend development)
|
||
|
||
---
|
||
|
||
### Environment Variables
|
||
Create a `.env` file at the repository root (or supply variables to your CI environment). Example:
|
||
|
||
```dotenv
|
||
# Database
|
||
POSTGRES_USER=your_user
|
||
POSTGRES_PASSWORD=your_password
|
||
|
||
# Connection string (used by the backend)
|
||
ConnectionStrings__PostgreSQL=Host=giecchallenge_db;Port=14432;Database=GiecChallenge;User ID=${POSTGRES_USER};Password=${POSTGRES_PASSWORD};Pooling=true
|
||
|
||
# JWT configuration
|
||
JWT__ValidAudience=https://giecchallenge-backend.maximeboulay.com
|
||
JWT__ValidIssuer=https://giecchallenge-backend.maximeboulay.com
|
||
JWT__Secret=super_secret_jwt_key
|
||
|
||
# UI configuration
|
||
REACT_APP_API_URL=http://localhost:17020 # points to the backend container
|
||
|
||
# Misc
|
||
OriginAllowed=http://localhost:3000
|
||
PasswordHash=some_hash_value
|
||
```
|
||
|
||
The `appsettings.Development.json` and `appsettings.Docker.json` files reference these variables using the `${VARIABLE_NAME}` syntax.
|
||
|
||
---
|
||
|
||
### Running Locally
|
||
1. **Start the stack**
|
||
|
||
```bash
|
||
docker compose up --build
|
||
```
|
||
|
||
- Backend API: `http://localhost:17020` (HTTP) & `https://localhost:17021` (HTTPS)
|
||
- Frontend UI: `http://localhost:13000`
|
||
- PostgreSQL: `localhost:14432`
|
||
|
||
2. **Access the UI** in a browser at `http://localhost:13000`.
|
||
|
||
3. **Stop the stack**
|
||
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
---
|
||
|
||
### Building & Testing
|
||
#### Backend
|
||
```bash
|
||
dotnet restore backend/GiecChallenge/GiecChallenge.csproj
|
||
dotnet build backend/GiecChallenge/GiecChallenge.csproj -c Release
|
||
dotnet test backend/GiecChallenge.test/GiecChallenge.test.csproj
|
||
```
|
||
|
||
#### Frontend
|
||
```bash
|
||
cd frontend
|
||
npm ci
|
||
npm run build # produces ./frontend/build
|
||
```
|
||
|
||
---
|
||
|
||
### Deploying with GitLab CI
|
||
The repository contains a `.gitlab-ci.yml` defining the following stages:
|
||
|
||
1. **restore** – restores NuGet packages and installs Node dependencies.
|
||
2. **build** – builds the .NET project and the React app.
|
||
3. **test** – runs backend unit tests.
|
||
4. **docker_build** – builds Docker images for both services and pushes them to the GitLab Container Registry.
|
||
5. **deploy** – placeholder stage for your production deployment (e.g., Kubernetes, Docker Swarm, or a VM).
|
||
|
||
The CI pipeline expects the following CI/CD variables to be defined in GitLab:
|
||
|
||
- `CI_REGISTRY_USER`, `CI_REGISTRY_PASSWORD`, `CI_REGISTRY`, `CI_REGISTRY_IMAGE` (provided automatically by GitLab).
|
||
- All custom variables from the `.env` file (e.g., `POSTGRES_USER`, `POSTGRES_PASSWORD`, `JWT__Secret`, etc.).
|
||
|
||
Push a branch, and GitLab will automatically run the pipeline. Merge to `main` to trigger the `deploy` stage placeholder.
|
||
|
||
---
|
||
|
||
### Project Structure
|
||
|
||
```
|
||
├── backend/
|
||
│ └── GiecChallenge/
|
||
│ ├── Dockerfile # Backend container image
|
||
│ ├── appsettings.*.json # Configuration files (environment‑variable placeholders)
|
||
│ ├── Controllers/ ...
|
||
│ └── *.csproj
|
||
├── frontend/
|
||
│ ├── Dockerfile # Frontend container image
|
||
│ ├── package.json
|
||
│ └── src/ …
|
||
├── docker-compose.yml # Local orchestration
|
||
├── .gitlab-ci.yml # CI pipeline definition
|
||
├── .env # Example env file (do not commit secrets)
|
||
└── README.md # You are reading it now
|
||
```
|
||
|
||
---
|
||
|
||
### License
|
||
This project is provided for educational purposes. Feel free to adapt and extend it under the terms of the MIT License.
|
||
|
||
---
|
||
|
||
**Enjoy!** If you encounter any issues, verify that all required environment variables are defined and that Docker is running with sufficient resources. |