fix and feat( Fix Synchro pages and tailwind/filament issues, clean read me, fix translations and seeders
Some checks failed
Deploy Roxane to Preprod / deploy (push) Failing after 26h12m0s
Some checks failed
Deploy Roxane to Preprod / deploy (push) Failing after 26h12m0s
This commit is contained in:
235
README.md
235
README.md
@@ -1,30 +1,211 @@
|
||||
# ROXANE - Centralized Portal with Laravel, React & Keycloak SSO
|
||||
# Roxane
|
||||
|
||||
This project is a **centralized portal application & web hosting association ERP** built with **Laravel 12 & React19**, designed to provide a seamless and secure entry point for both **end users** and **administrators**.
|
||||
Roxane is an open source membership management application designed for associations. It centralizes member management, subscriptions, and integration with self-hosted third-party services (Dolibarr, ISPConfig, Nextcloud, Sympa).
|
||||
|
||||
- **Front Office (Users)**
|
||||
- Build on React19
|
||||
- (V2) Authentication via **Keycloak SSO (OIDC)**
|
||||
- Unified dashboard to access external applications (cloud storage, mailing tools, file sharing, etc.)
|
||||
- Role-based access control synced from Keycloak
|
||||
- Connected with : ISP Config for web hosting and mailbox management, NextCloud, Sympa for mailing list and more...
|
||||
- **Back Office (Admins)**
|
||||
- Authentication handled **locally in Laravel** (separate from Keycloak)
|
||||
- Built with **FilamentPHP**
|
||||
- Advanced admin features: app configuration, user activity logs, monitoring
|
||||
- **Security & API**
|
||||
- JWT validation for user-facing APIs (via Keycloak)
|
||||
- Laravel Sanctum / API tokens for admin endpoints
|
||||
- Support for MFA, Single Logout, and audit logging
|
||||
- **Tech Stack Highlights**
|
||||
- Laravel 12 (PHP 8.3)
|
||||
- Blade + Livewire (back office UI)
|
||||
- React19 (front office UI)
|
||||
- TailwindCSS (UI framework)
|
||||
- Keycloak SSO (OIDC) (V2)
|
||||
- FilamentPHP (admin panel)
|
||||
- Redis (cache, sessions, queues)
|
||||
- Maria DB
|
||||
- Docker-ready + CI/CD support and automated deploy
|
||||
The project is developed in the context of **Le Retzien Libre**, a non-profit association promoting digital freedom and self-hosting. It is intended to be generic enough to be adapted by other associations with similar needs.
|
||||
|
||||
This architecture allows associations to **centralize authentication and app access** while keeping the **admin back office independent and highly secure**.
|
||||
> Work in progress. The application is functional for core features but is actively being developed. See the [known TODOs](#known-todos) section.
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
**Back office (administrators)**
|
||||
- Member management (status, nature, groups)
|
||||
- Subscription and package management
|
||||
- Manual and automated synchronization with third-party services
|
||||
- Role and permission management (Spatie Permissions + Filament Shield)
|
||||
- Two-factor authentication for admin accounts
|
||||
|
||||
**Front office (members)**
|
||||
- Registration and membership form
|
||||
- Personal dashboard with access to associated services
|
||||
- Profile and password management
|
||||
- Two-factor authentication
|
||||
|
||||
**Integrations**
|
||||
- Dolibarr ERP (member and subscription import via REST API)
|
||||
- ISPConfig (mail and web hosting account management via SOAP)
|
||||
- Nextcloud (account provisioning via OCS API)
|
||||
- Sympa (mailing list management)
|
||||
|
||||
**Planned in V2**
|
||||
- SSO authentication via Keycloak (OIDC) for the front office
|
||||
- Admin back office remains on local Laravel authentication
|
||||
|
||||
---
|
||||
|
||||
## Tech stack
|
||||
|
||||
| Layer | Technologies |
|
||||
|-----------|-------------------------------------------------------|
|
||||
| Backend | Laravel 12, PHP 8.3, MySQL |
|
||||
| Admin | Filament v4, Livewire 3 |
|
||||
| Frontend | React 19, Inertia v2, Tailwind CSS v4 |
|
||||
| Auth | Laravel Fortify, 2FA, Spatie Permissions + Shield |
|
||||
| Queue | Redis (cache, sessions, queues) |
|
||||
| Tests | PHPUnit 11 |
|
||||
| Dev tools | Pint, ESLint, Prettier, Laravel Sail, Wayfinder |
|
||||
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
- PHP 8.3+
|
||||
- Composer
|
||||
- Node.js 20+ and npm
|
||||
- MySQL 8+ or MariaDB 10.6+
|
||||
- Redis
|
||||
- Docker (optional, via Laravel Sail)
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
### 1. Clone the repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/your-org/roxane.git
|
||||
cd roxane
|
||||
```
|
||||
|
||||
### 2. Install dependencies
|
||||
|
||||
```bash
|
||||
composer install
|
||||
npm install
|
||||
```
|
||||
|
||||
### 3. Environment configuration
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
php artisan key:generate
|
||||
```
|
||||
|
||||
Edit `.env` and configure:
|
||||
- Database connection (`DB_*`)
|
||||
- Redis connection (`REDIS_*`)
|
||||
- Mail configuration (`MAIL_*`)
|
||||
- Third-party service credentials (Dolibarr, ISPConfig, Nextcloud)
|
||||
|
||||
### 4. Database setup
|
||||
|
||||
```bash
|
||||
php artisan migrate
|
||||
php artisan db:seed
|
||||
```
|
||||
|
||||
The seeder creates:
|
||||
- Member groups (`admin-interface`, `website`)
|
||||
- Default packages (`custom`, `one-year`, `two-years`)
|
||||
- Default services (mail, file2link, nextcloud, sympa, webhosting)
|
||||
- Admin account (`contact@nebulae-design.com` / `password`)
|
||||
- Notification templates
|
||||
|
||||
In non-production environments, a demo member (Jane Doe) is also created.
|
||||
|
||||
**Change all default credentials immediately after installation.**
|
||||
|
||||
### 5. Build frontend assets
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
For local development with hot reload:
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Or use the all-in-one development command:
|
||||
|
||||
```bash
|
||||
composer run dev
|
||||
```
|
||||
|
||||
### 6. Queues and scheduler
|
||||
|
||||
The application uses queued jobs for synchronization tasks and notifications. In production, configure a queue worker and the Laravel scheduler.
|
||||
|
||||
```bash
|
||||
# Queue worker
|
||||
php artisan queue:work
|
||||
|
||||
# Scheduler (add to crontab)
|
||||
* * * * * cd /path/to/roxane && php artisan schedule:run >> /dev/null 2>&1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Running with Laravel Sail (Docker)
|
||||
|
||||
```bash
|
||||
./vendor/bin/sail up -d
|
||||
./vendor/bin/sail artisan migrate
|
||||
./vendor/bin/sail artisan db:seed
|
||||
./vendor/bin/sail npm run build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Default accounts
|
||||
|
||||
| Account | Email | Password | Role |
|
||||
|-------------|----------------------------|----------|-------------|
|
||||
| Admin | contact@nebulae-design.com | password | super_admin |
|
||||
| Demo member | jane@doe.com | password | — |
|
||||
|
||||
These accounts are created by the seeder. Remove or change them before any production deployment.
|
||||
|
||||
---
|
||||
|
||||
## Artisan commands
|
||||
|
||||
Synchronization commands can be triggered manually from the admin panel (Synchronisations page) or via CLI:
|
||||
|
||||
| Command | Description |
|
||||
|-------------------------------|--------------------------------------------------------------|
|
||||
| `sync:dolibarr-members` | Import members and subscriptions from Dolibarr |
|
||||
| `members:cleanup-expired` | Deactivate expired members across all services (`--dry-run`) |
|
||||
| `sync:ispconfig-mail-members` | Link members to their ISPConfig mail accounts |
|
||||
| `sync:ispconfig-web-members` | Link members to their ISPConfig web hosting accounts |
|
||||
| `nextcloud:sync-members` | Link members to their Nextcloud accounts |
|
||||
| `memberships:sync-services` | Synchronize services associated with active memberships |
|
||||
|
||||
---
|
||||
|
||||
## Running tests
|
||||
|
||||
```bash
|
||||
php artisan test --compact
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Known TODOs
|
||||
|
||||
| Area | Description |
|
||||
|---------------------------|---------------------------------------------------------------------|
|
||||
| ContactService | Send email notification to administrator on new contact request |
|
||||
| MemberService | Send emails to member and admin on deactivation |
|
||||
| SubscriptionExpiredPhase1 | Generic template + backend UI for notification content management |
|
||||
| User.php | Restrict admin access in production to @retzien.fr emails |
|
||||
| SyncDolibarrMembers | Extract `toDate()` method into a shared service or helper |
|
||||
| SyncISPConfigMailMembers | Handle multiple email addresses per member |
|
||||
| SyncISPConfigMailMembers | Track `ispconfig_client_id` |
|
||||
| Global | Make Roxane fully generic for any association ERP use case |
|
||||
| Translations | Audit project for missing translation keys |
|
||||
| Global | Raise PHPStan to level 8 |
|
||||
| V2 | Keycloak SSO integration (OIDC) for front office authentication |
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the [GNU Affero General Public License v3.0](LICENSE) (AGPL-3.0).
|
||||
|
||||
Any modification to the source code, including versions run as a network service, must be made available under the same license. This ensures the project remains free and open for all.
|
||||
|
||||
Contributions are welcome. If you are adapting Roxane for your own association, feel free to open an issue or submit a pull request.
|
||||
|
||||
Reference in New Issue
Block a user