Skip to content

Commit ea4447e

Browse files
Paul2803kMaartendeKruijf
Paul2803k
authored and
MaartendeKruijf
committed
📝 doc: update README
1 parent bca83a6 commit ea4447e

1 file changed

Lines changed: 286 additions & 25 deletions

File tree

‎README.md‎

Lines changed: 286 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -5,56 +5,317 @@
55
# SOARCA-GUI
66

77
[![https://cossas-project.org/portfolio/SOARCA/](https://img.shields.io/badge/website-cossas.github.io-orange)](https://cossas.github.io/SOARCA/docs/)
8+
[![Release](https://img.shields.io/github/v/release/cossas/soarca-gui?label=release&sort=semver)](https://github.com/cossas/soarca-gui/releases)
89
[![Pipeline status](https://github.com/cossas/soarca-gui/actions/workflows/ci.yml/badge.svg?development)](https://github.com/COSSAS/SOARCA/actions)
910
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
1011

1112
Modern [React](https://react.dev) + [Vite](https://vitejs.dev) frontend for the [SOARCA](https://github.com/COSSAS/SOARCA) platform, providing a lightweight UI to interact with SOARCA services. The app uses [TypeScript](https://www.typescriptlang.org/), [styled-components](https://styled-components.com/) for theming, [React Router](https://reactrouter.com/) for navigation, and [React Query](https://tanstack.com/query) for data fetching.
1213

1314
> [!WARNING]
14-
> SOARCA-GUI is still in development and features for the base version v0.1 are still being added.
15+
> SOARCA-GUI is still in development and features and look may change with time.
1516
16-
## Requirements for running
17+
## Requirements
1718

18-
- [Node.js](https://nodejs.org/) 20+
19-
- [npm](https://www.npmjs.com/) 10+
20-
- (Optional) [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/) for running the full stack locally
19+
- [Node.js](https://nodejs.org/) 20+ (if runned locally)
20+
- [npm](https://www.npmjs.com/) 10+ (if runned locally)
21+
- [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/) (for building/running from docker image)
2122

22-
## Getting Started (Development)
23+
## Running the Project
24+
25+
### Development Mode
26+
27+
Development mode provides hot-reload capabilities and a proxy server for API requests to the SOARCA backend. In order to provide an enjoyable development experience, we provide both a local environment and a Docker setup. In order to accomodate both scenarios and provided minimal user configuration needed, we opted for the architecture shown below.
28+
29+
#### Development Architecture
30+
31+
Development can happen in two ways: locally running Vite on your machine or in a Docker container.
32+
33+
```mermaid
34+
flowchart TB
35+
subgraph User[" "]
36+
direction TB
37+
UserLabel["User Machine"]
38+
Browser["Browser<br/>localhost:HOST_PORT"]
39+
end
40+
41+
subgraph LocalDev["Local Development Mode"]
42+
direction TB
43+
LocalLabel["Local Development"]
44+
LocalVite["Vite Dev Server<br/>Port: VITE_SERVER_PORT"]
45+
LocalProxy["Vite Proxy<br/>/api → VITE_BACKEND_URL"]
46+
LocalHMR["Hot Module<br/>Replacement"]
47+
end
48+
49+
subgraph DockerDev["Docker Container Mode"]
50+
direction TB
51+
ContainerLabel["Development Container"]
52+
ContainerVite["Vite Dev Server<br/>Port: VITE_SERVER_PORT"]
53+
ContainerProxy["Vite Proxy<br/>/api → VITE_BACKEND_URL"]
54+
ContainerHMR["Hot Module<br/>Replacement"]
55+
end
56+
57+
subgraph Backend[" "]
58+
direction TB
59+
BackendLabel["SOARCA Backend"]
60+
API["API Endpoints"]
61+
end
62+
63+
UserLabel ~~~ Browser
64+
LocalLabel ~~~ LocalVite
65+
ContainerLabel ~~~ ContainerVite
66+
BackendLabel ~~~ API
67+
68+
%% Local development flow
69+
Browser -->|Local Mode| LocalVite
70+
LocalVite -->|Source Files| LocalHMR
71+
LocalHMR -->|Live Updates| Browser
72+
Browser -->|"/api/*"| LocalProxy
73+
LocalProxy -->|"Rewrite & Forward"| API
74+
75+
%% Docker development flow
76+
Browser -->|Container Mode| ContainerVite
77+
ContainerVite -->|Source Files| ContainerHMR
78+
ContainerHMR -->|Live Updates| Browser
79+
Browser -->|"/api/*"| ContainerProxy
80+
ContainerProxy -->|"Rewrite & Forward"| API
81+
82+
%% Backend responses
83+
API -->|Response| LocalProxy
84+
LocalProxy -->|Response| Browser
85+
API -->|Response| ContainerProxy
86+
ContainerProxy -->|Response| Browser
87+
88+
style LocalVite fill:#C5E1FF,stroke:#4A90E2,color:#000
89+
style ContainerVite fill:#C5E1FF,stroke:#4A90E2,color:#000
90+
style Browser fill:#B8F5D3,stroke:#2ECC71,color:#000
91+
style API fill:#FFE5CC,stroke:#E67E22,color:#000
92+
style LocalHMR fill:#FFD1DC,stroke:#E74C3C,color:#000
93+
style ContainerHMR fill:#FFD1DC,stroke:#E74C3C,color:#000
94+
style LocalProxy fill:#C2F0F0,stroke:#16A085,color:#000
95+
style ContainerProxy fill:#C2F0F0,stroke:#16A085,color:#000
96+
97+
style UserLabel fill:#F0F0F0,stroke:#999,color:#333
98+
style LocalLabel fill:#F0F0F0,stroke:#999,color:#333
99+
style ContainerLabel fill:#F0F0F0,stroke:#999,color:#333
100+
style BackendLabel fill:#F0F0F0,stroke:#999,color:#333
101+
102+
classDef envVar fill:#D4F1D4,stroke:#27AE60,stroke-width:2px,color:#000
103+
class VITE_SERVER_PORT envVar
104+
class HOST_PORT envVar
105+
class VITE_BACKEND_URL envVar
106+
```
107+
108+
**Environment variables involved:**
109+
110+
- `VITE_BACKEND_URL` - Backend API URL (proxied by Vite dev server)
111+
- `VITE_SERVER_PORT` - Port where Vite dev server listens
112+
- `DOCKER_HOST_PORT` - The port of the host machine that is mapped to the `VITE_SERVER_PORT` of the Vite dev server running in the container. This is only relevant when running the Development Container.
113+
- `HOST_PORT` - is the same of the `VITE_SERVER_PORT` if run locally or `DOCKER_HOST_PORT` if running the Development Container.
114+
115+
#### Running Locally (recommended for development)
116+
117+
1. **Install (dev)dependencies:**
23118

24-
1. Install dependencies:
25119
```bash
26-
npm install
120+
npm install -D
27121
```
28-
2. Start the dev server (Vite):
122+
123+
2. **Configure environment variables:**
124+
Optionally create a `.env` file (explanation and defaults can be found in `.env.example`). Vite will load `*.env` files for the active mode and only expose variables that begin with `VITE_` to the browser (see https://vite.dev/guide/env-and-mode).
125+
126+
If no enviroment variables are provided, the defaults are:
127+
- `VITE_BACKEND_URL`: `http://localhost:8080` - (SOARCA default)
128+
- `VITE_SERVER_PORT`: `5713` - (Vite default)
129+
130+
3. **Start the dev server:**
131+
29132
```bash
30133
npm run dev
31134
```
32-
The dev server runs at http://localhost:3000 but the port can be modified in the `vite.config.ts` and `Dockerfile`.
33135

34-
## NPM Scripts
136+
The app will be available at `http://localhost:HOST_PORT` with hot-reload enabled. You will see in the terminal where exactly the app is being served.
35137

36-
- `npm run dev` — start Vite dev server
37-
- `npm run lint` — run ESLint
38-
- `npm run build` — type-check and create production bundle
39-
- `npm run preview` — serve the production build locally
138+
#### Running in Docker Container (reccomended for development without Node/npm setup)
40139

41-
## Running with Docker (optional)
140+
1. **Configure environment variables:**
141+
Optionally provide values via the shell, a project `.env`, or `--env-file` when starting Compose (explanation and defaults can be found in `.env.example`).
42142

43-
Currently the docker image in not published yet, so you will have to buid your own
143+
If no enviroment variables are provided, the defaults are:
144+
- `VITE_BACKEND_URL`: `http://host.docker.internal:8080` - (The `localhost:8080` equivalent of the Container internal network)
145+
- `VITE_SERVER_PORT`: `5173`
146+
- `DOCKER_HOST_PORT` — port on the host mapped to the `VITE_SERVER_PORT` (default: `5173`)
44147

45-
```bash
46-
docker build -t soarca-ui-react-dev --target development .
47-
```
148+
2. **Start the container:**
149+
```bash
150+
docker compose -f docker-compose.dev.yml up
151+
```
152+
The app will be available at `http://localhost:HOST_PORT` with hot-reload enabled.
153+
154+
### Production Mode
155+
156+
Production mode builds optimized static assets and serves them via Nginx. We use this mode to publish Docker images and make releases, but it can be useful to run a production build locally through Vite as well by building the project locally and previewing it. Also this mode is supported for both local and Docker Container environment.
157+
As before, a diagram of the architecture is shown down below.
158+
159+
#### Production Architecture
160+
161+
Production deployment can happen in two ways: locally using Vite's preview server or in a Docker container using Nginx.
162+
163+
```mermaid
164+
flowchart TB
165+
subgraph User[" "]
166+
direction TB
167+
UserLabel["User Machine"]
168+
Browser["Browser<br/>localhost:HOST_PORT"]
169+
end
48170
49-
To spin up the UI with the included compose setup:
171+
subgraph LocalProd["Local Production Mode"]
172+
direction TB
173+
LocalLabel["Local Build & Preview"]
174+
LocalBuild["npm run build"]
175+
LocalDist["dist/<br/>Static Assets"]
176+
VitePreview["Vite Preview Server<br/>Port: 3000<br/>Proxy: VITE_BACKEND_URL"]
177+
end
50178
51-
```bash
52-
docker compose up -d
179+
subgraph DockerProd["Docker Container Mode"]
180+
direction TB
181+
ContainerLabel["Multi-stage Docker Build"]
182+
183+
subgraph BuildStage[" "]
184+
direction TB
185+
BuildLabel["Build Stage"]
186+
NPM["npm install"]
187+
Build["npm run build"]
188+
Dist["dist/"]
189+
end
190+
191+
subgraph ProdStage[" "]
192+
direction TB
193+
ProdLabel["Production Stage"]
194+
StaticFiles["Static Files<br/>/usr/share/nginx/html"]
195+
NginxConf["Nginx Config<br/>Port: NGINX_SERVER_PORT<br/>Proxy: NGINX_BACKEND_URL"]
196+
Nginx["Nginx Server"]
197+
end
198+
end
199+
200+
subgraph Backend[" "]
201+
direction TB
202+
BackendLabel["SOARCA Backend"]
203+
API["API Endpoints"]
204+
end
205+
206+
UserLabel ~~~ Browser
207+
LocalLabel ~~~ LocalBuild
208+
ContainerLabel ~~~ BuildStage
209+
BuildLabel ~~~ NPM
210+
ProdLabel ~~~ StaticFiles
211+
BackendLabel ~~~ API
212+
213+
%% Local production flow
214+
LocalBuild --> LocalDist
215+
LocalDist --> VitePreview
216+
Browser -->|Local Mode| VitePreview
217+
VitePreview -->|"/api/*"| API
218+
219+
%% Docker production flow
220+
NPM --> Build
221+
Build --> Dist
222+
Dist -->|Copy| StaticFiles
223+
StaticFiles --> Nginx
224+
Nginx --> NginxConf
225+
Browser -->|Container Mode| Nginx
226+
NginxConf -->|"/api/*"| API
227+
API -->|Response| NginxConf
228+
NginxConf -->|Response| Browser
229+
API -->|Response| VitePreview
230+
VitePreview -->|Response| Browser
231+
232+
style LocalBuild fill:#C5E1FF,stroke:#4A90E2,color:#000
233+
style Build fill:#C5E1FF,stroke:#4A90E2,color:#000
234+
style Browser fill:#B8F5D3,stroke:#2ECC71,color:#000
235+
style API fill:#FFE5CC,stroke:#E67E22,color:#000
236+
style VitePreview fill:#C2F0F0,stroke:#16A085,color:#000
237+
style Nginx fill:#C2F0F0,stroke:#16A085,color:#000
238+
style NginxConf fill:#C2F0F0,stroke:#16A085,color:#000
239+
style LocalDist fill:#FFF4CC,stroke:#F39C12,color:#000
240+
style Dist fill:#FFF4CC,stroke:#F39C12,color:#000
241+
style StaticFiles fill:#FFF4CC,stroke:#F39C12,color:#000
242+
style NPM fill:#E8D4FF,stroke:#9B59B6,color:#000
243+
244+
style UserLabel fill:#F0F0F0,stroke:#999,color:#333
245+
style LocalLabel fill:#F0F0F0,stroke:#999,color:#333
246+
style ContainerLabel fill:#F0F0F0,stroke:#999,color:#333
247+
style BuildLabel fill:#F0F0F0,stroke:#999,color:#333
248+
style ProdLabel fill:#F0F0F0,stroke:#999,color:#333
249+
style BackendLabel fill:#F0F0F0,stroke:#999,color:#333
250+
251+
classDef envVar fill:#D4F1D4,stroke:#27AE60,stroke-width:2px,color:#000
252+
class VITE_BACKEND_URL envVar
253+
class NGINX_BACKEND_URL envVar
254+
class NGINX_SERVER_PORT envVar
255+
class HOST_PORT envVar
53256
```
54257

55-
## Hot-reload
258+
**Environment variables involved:**
259+
260+
- `VITE_BACKEND_URL` - Backend API URL embedded into the client bundle at build time (must be set before running `npm run build`)
261+
- `VITE_APP_VERSION` - Application version embedded into the client bundle at build time (optional, falls back to git describe or "development")
262+
- `NGINX_BACKEND_URL` - Backend API URL used by Nginx at runtime to proxy `/api/*` requests. This is only relevant when running in Docker Container Mode.
263+
- `NGINX_SERVER_PORT` - Port where Nginx listens inside the container. This is only relevant when running in Docker Container Mode.
264+
- `DOCKER_HOST_PORT` - The port of the host machine that is mapped to the `NGINX_SERVER_PORT` of the Nginx server running in the container. This is only relevant when running in Docker Container Mode.
265+
- `HOST_PORT` - Port 4173 (Vite default) for local preview mode (`npm run preview`) or `DOCKER_HOST_PORT` when running in Docker Container Mode.
266+
267+
#### Running Locally (recommended for preview)
268+
269+
1. **Install dependencies:**
270+
271+
```bash
272+
npm install
273+
```
274+
275+
2. **Configure environment variables:**
276+
Optionally create a `.env` file (explanation and defaults can be found in `.env.example`). Note that `VITE_` variables must be set at _build time_ to be embedded into the static bundle.
277+
278+
If no environment variables are provided, the defaults are:
279+
- `VITE_BACKEND_URL`: `http://localhost:8080` - (SOARCA default)
280+
281+
3. **Build and preview:**
282+
283+
```bash
284+
npm run build
285+
npm run preview
286+
```
287+
288+
The app will be available at `http://localhost:4173` (Vite preview server default).
289+
290+
> [!WARNING]
291+
> For actual production deployment, use a proper web server like Nginx (see Docker section below).
292+
293+
#### Running in Docker Container (recommended for production)
294+
295+
1. **Configure environment variables:**
296+
Optionally provide values via the shell, a project `.env`, or `--env-file` when starting Compose (explanation and defaults can be found in `.env.example`). Note that `VITE_` variables are build-time only (embedded at image build), while `NGINX_` variables are runtime (used by the running container).
297+
298+
If no environment variables are provided, the defaults are:
299+
- `VITE_BACKEND_URL`: `http://localhost:8080` - embedded at build time
300+
- `NGINX_BACKEND_URL`: `http://host.docker.internal:8080/` - used at runtime
301+
- `NGINX_SERVER_PORT`: `8081`
302+
- `DOCKER_HOST_PORT`: `8081` — port on the host mapped to the `NGINX_SERVER_PORT`
303+
304+
2. **Build and start the container:**
305+
306+
```bash
307+
docker compose up --build
308+
```
309+
310+
The app will be available at `http://localhost:DOCKER_HOST_PORT`.
311+
312+
### NPM Scripts for local run
56313

57-
In both the local and Docker dev environment, Vite provides instant hot reload, so any change to the files will be reflected in the browser upon saving.
314+
- `npm run dev` - Start Vite dev server with hot-reload
315+
- `npm run build` - Type-check and create production bundle
316+
- `npm run preview` - Serve the production build locally (Vite preview server)
317+
- `npm run lint` - Run ESLint
318+
- `npm test` - Run unit tests (Vitest)
58319

59320
## Documentation
60321

0 commit comments

Comments
 (0)