Create README
This commit is contained in:
Maxime Boulay
148
README.md
Normal file
148
README.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user