Nebulae
2e44eed699
Some checks failed
Deploy Roxane to Preprod / deploy (push) Failing after 26h12m0s
212 lines
6.9 KiB
Markdown
212 lines
6.9 KiB
Markdown
# Roxane
|
|
|
|
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).
|
|
|
|
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.
|
|
|
|
> 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.
|