chore: restructure into monorepo and add open-source documentation
- Rename helix-server -> server and helix-web -> web - Remove helix-api (bruno collection and docs site) - Merge per-module .gitignore files into the root .gitignore - Add README, AGENTS, CONTRIBUTING and MIT LICENCE - Add full-stack docker-compose (postgres, redis, server, web via Caddy) with web Dockerfile, Caddyfile and Compose server config - Keep the Gradle wrapper jar tracked after the .gitignore merge - Copy gradle.properties into the server Docker build image
This commit is contained in:
315 files changed
+741
-7394
No files matched your search
@@ -0,0 +1,156 @@
|
||||
# Helix
|
||||
|
||||
Helix is a self-hosted identity and access management (IAM) and organisation
|
||||
administration platform built by [OnixByte](https://onixbyte.com). It manages
|
||||
users, roles, departments, positions and navigation menus behind a single
|
||||
sign-on experience, with support for Microsoft Entra ID (Azure AD), WeCom
|
||||
(WeChat Work) and multi-factor authentication.
|
||||
|
||||
The project is organised as a monorepo:
|
||||
|
||||
- **`server/`** — Spring Boot 3 REST API (Java 21, PostgreSQL, Redis, Flyway)
|
||||
- **`web/`** — React 19 single-page application (Vite, Ant Design, Tailwind CSS, Redux Toolkit)
|
||||
- **`docker/`** — deployment support files used by Docker Compose
|
||||
|
||||
## Features
|
||||
|
||||
- **Authentication & single sign-on** — username/password login with captcha,
|
||||
Microsoft Entra ID (MSAL) sign-in, WeCom login and MFA
|
||||
- **User management** — create, edit and deactivate users; assign roles, departments and positions
|
||||
- **Role-based access control** — roles with fine-grained authorities, enforced across all endpoints
|
||||
- **Organisation management** — departments, positions and custom navigation menus
|
||||
- **Asset storage** — optional S3-compatible object storage for uploaded files
|
||||
- **Internationalisation** — English (`en-GB`) and Chinese (`zh-CN`) message bundles
|
||||
- **Responsive admin UI** — Ant Design + Tailwind CSS front end
|
||||
|
||||
## Tech stack
|
||||
|
||||
| Layer | Technologies |
|
||||
| ----------- | ------------ |
|
||||
| Backend | Java 21 · Spring Boot 3.5 · Spring Security · Spring Data JPA · MyBatis · Flyway · PostgreSQL · Redis · Auth0 java-jwt · AWS SDK for Java (S3) |
|
||||
| Frontend | React 19 · TypeScript · Vite 7 · Ant Design 6 · Tailwind CSS 4 · Redux Toolkit · React Router 7 · Axios · MSAL |
|
||||
| Infra | Docker · Docker Compose · Caddy |
|
||||
|
||||
## Repository layout
|
||||
|
||||
```
|
||||
.
|
||||
├── server/ # Spring Boot REST API
|
||||
│ ├── src/main/java/com/onixbyte/helix/
|
||||
│ │ ├── controller/ # HTTP entry points
|
||||
│ │ ├── service/ # business logic
|
||||
│ │ ├── manager/ # use-case orchestration
|
||||
│ │ ├── repository/ # JPA repositories
|
||||
│ │ ├── mapper/ # MyBatis mappers
|
||||
│ │ ├── validation/ # custom validation framework
|
||||
│ │ └── security/ # JWT filter, security configuration
|
||||
│ ├── src/main/resources/
|
||||
│ │ ├── db/migrations/ # Flyway SQL migrations
|
||||
│ │ ├── i18n/ # message bundles (en-GB, zh-CN)
|
||||
│ │ └── mapper/ # MyBatis XML mappers
|
||||
│ ├── config/ # runtime config (see application-prod.yml.example)
|
||||
│ └── Dockerfile
|
||||
├── web/ # React SPA
|
||||
│ ├── src/api/ # typed API clients (auth, user, role, …)
|
||||
│ ├── src/page/ # page components
|
||||
│ ├── src/store/ # Redux slices
|
||||
│ ├── src/router/ # react-router routes
|
||||
│ ├── Dockerfile # builds the SPA and serves it with Caddy
|
||||
│ └── Caddyfile # static files + /api reverse proxy
|
||||
├── docker/ # Compose support files
|
||||
│ └── application-prod.yml # server config mounted into the container
|
||||
├── docker-compose.yaml # full-stack: postgres + redis + server + web
|
||||
└── .env.example # Compose environment template
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
### Full stack with Docker Compose
|
||||
|
||||
Requires [Docker](https://www.docker.com/) with the Compose plugin.
|
||||
|
||||
```bash
|
||||
cp .env.example .env # optional: adjust ports, secrets and integrations
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
Once the containers are healthy:
|
||||
|
||||
| Service | URL |
|
||||
| ------------------ | ---------------------------------- |
|
||||
| Web UI | <http://localhost> |
|
||||
| REST API | <http://localhost:8080> |
|
||||
| Health check | <http://localhost:8080/actuator/health> |
|
||||
|
||||
Login works out of the box with username/password + captcha. Microsoft Entra ID
|
||||
and WeCom sign-in require configuring their credentials (see below).
|
||||
|
||||
### Manual development
|
||||
|
||||
#### Server (JDK 21)
|
||||
|
||||
```bash
|
||||
cd server
|
||||
cp config/application-prod.yml.example config/application-prod.yml # edit to match your environment
|
||||
SPRING_PROFILES_ACTIVE=prod ./gradlew bootRun
|
||||
```
|
||||
|
||||
The API starts on <http://localhost:8080>.
|
||||
|
||||
#### Web (Node 22+ with pnpm)
|
||||
|
||||
```bash
|
||||
cd web
|
||||
pnpm install
|
||||
cp .env.example .env.development.local # point the API base URL at your dev server
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
Set `VITE_API_BASE_URL=http://localhost:8080` in `.env.development.local` to call
|
||||
the locally running API directly. The Vite dev server listens on
|
||||
<http://localhost:5173>.
|
||||
|
||||
## Configuration
|
||||
|
||||
Runtime configuration is externalised through environment variables (see
|
||||
`server/config/application-prod.yml.example` for the complete reference).
|
||||
|
||||
### Docker Compose (`.env`)
|
||||
|
||||
| Variable | Default | Description |
|
||||
| -------------------------- | ------------------------- | ---------------------------------------------- |
|
||||
| `PG_DATABASE` | `helix` | PostgreSQL database name |
|
||||
| `PG_USER` | `helix` | PostgreSQL user |
|
||||
| `PG_PASSWORD` | `helix` | PostgreSQL password |
|
||||
| `REDIS_PASSWORD` | *(empty)* | Redis password (leave empty for local Redis) |
|
||||
| `TOKEN_SECRET` | *(see example)* | JWT signing secret — change in production |
|
||||
| `MSAL_CLIENT_ID` | *(empty)* | Microsoft Entra ID application (client) ID |
|
||||
| `MSAL_TENANT_ID` | *(empty)* | Microsoft Entra ID tenant ID |
|
||||
| `S3_ACCESS_KEY_ID` | *(empty)* | S3 access key (requires enabling asset storage)|
|
||||
| `S3_SECRET_ACCESS_KEY` | *(empty)* | S3 secret key |
|
||||
| `SERVER_PORT` | `8080` | Host port mapped to the server container |
|
||||
| `WEB_PORT` | `80` | Host port mapped to the Caddy container |
|
||||
|
||||
Asset storage is disabled in `docker/application-prod.yml` by default. To enable
|
||||
it, set `app.asset.enabled: true` there and provide the `S3_*` variables.
|
||||
|
||||
### Web (`.env`)
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ------------------------------- | ---------------------------------- | ---------------------------------- |
|
||||
| `VITE_API_BASE_URL` | `/api` | Backend base URL |
|
||||
| `VITE_MSAL_CLIENT_ID` | *(empty)* | Microsoft Entra ID client ID |
|
||||
| `VITE_MSAL_TENANT_ID` | *(empty)* | Microsoft Entra ID tenant ID |
|
||||
| `VITE_DEFAULT_REGION_ABBREVIATION` | `GB` | Default user region (ISO 3166-1 alpha-2) |
|
||||
| `VITE_APP_TITLE` | `Onixbyte Technology Co., Ltd` | Application title shown in the UI |
|
||||
|
||||
## Development
|
||||
|
||||
- Architecture and conventions are documented in [AGENTS.md](AGENTS.md).
|
||||
- See [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute.
|
||||
- Database schema is managed with Flyway — add migrations under
|
||||
`server/src/main/resources/db/migrations/` rather than relying on JPA `ddl-auto`.
|
||||
|
||||
## License
|
||||
|
||||
[MIT](LICENCE) © OnixByte
|
||||
Reference in new issue
Block a user