Skip to content

Commit 9c4c150

Browse files
gavinmcfallgavinmcfall
committed
Add server-documentation plugin for Pelican Panel
A documentation management plugin that allows administrators to create, organize, and distribute documentation to server users with granular permission-based visibility. Features: - Rich text editor with WYSIWYG editing - 4-tier permission system (Host Admin, Server Admin, Server Mod, Player) - Global and server-specific documentation - Server assignment during creation with egg-based filtering - Version history with preview and restore functionality - Markdown import/export with YAML frontmatter support - Drag-and-drop reordering in relation managers - Audit logging with configurable channel - Caching with tag support and fallback for non-tagging drivers Security: - HTML sanitization on markdown import - Authorization checks on all endpoints - Rate limiting on version creation - XSS prevention via html_input escaping Infrastructure: - Cross-database compatibility (MySQL, PostgreSQL, SQLite) - Comprehensive test suite with Pest PHP - Model factories for testing - Configurable via environment variables
1 parent bacb6a5 commit 9c4c150

52 files changed

Lines changed: 4910 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎server-documentation/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 Gavin
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎server-documentation/README.md‎

Lines changed: 362 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,362 @@
1+
# Server Documentation Plugin for Pelican Panel
2+
3+
A documentation management plugin for [Pelican Panel](https://pelican.dev) that allows administrators to create, organize, and distribute documentation to server users with granular permission-based visibility.
4+
5+
## Features
6+
7+
- **Rich Text Editor** - Full WYSIWYG editing with formatting, lists, code blocks, tables, and more
8+
- **4-Tier Permission System** - Control who sees what documentation based on their role
9+
- **Global & Server-Specific Docs** - Create documentation that appears on all servers or only specific ones
10+
- **Server Assignment During Creation** - Assign documents to servers with egg-based filtering when creating
11+
- **Version History** - Track changes with automatic versioning, rate-limited to prevent spam
12+
- **Markdown Import/Export** - Import `.md` files or export documents for backup/migration
13+
- **Server Panel Integration** - Documents appear in the player's server sidebar with search
14+
- **Admin Panel Integration** - Full CRUD management with filtering, search, and bulk actions
15+
- **Drag-and-Drop Reordering** - Easily reorder documents in relation managers
16+
- **Audit Logging** - All document operations are logged for accountability
17+
18+
## Screenshots
19+
20+
### Admin Panel - Document List
21+
![Admin Documents List](docs/images/admin-documents-list.png)
22+
*Full document management with Import Markdown action, type badges, and global indicators*
23+
24+
### Admin Panel - Create Document
25+
![Admin Create Document](docs/images/admin-create-document.png)
26+
*Permission type selector with all 4 tiers visible in dropdown*
27+
28+
### Admin Panel - Edit Document with Linked Servers
29+
![Admin Edit Document](docs/images/admin-edit-document.png)
30+
*Rich text editor with Servers relation manager showing linked servers*
31+
32+
### Server Panel - Server Admin View
33+
![Server Admin View](docs/images/server-admin-view.png)
34+
*Server admins see "Server Admin", "Server Mod", and "Player" documents (4 docs)*
35+
36+
### Server Panel - Server Mod View
37+
![Server Mod View](docs/images/server-mod-view.png)
38+
*Server mods see "Server Mod" and "Player" documents, including the Moderator Handbook (3 docs)*
39+
40+
### Server Panel - Player View
41+
![Player View](docs/images/player-view.png)
42+
*Players only see documents marked as "Player" type (2 docs)*
43+
44+
### Version History
45+
![Version History](docs/images/version-history.png)
46+
*Version table with change summaries showing character diff (e.g., "+2 chars")*
47+
48+
### Version Preview
49+
![Version Preview](docs/images/version-history-preview.png)
50+
*Preview modal showing full content of a previous version*
51+
52+
### Version Restore
53+
![Version Restore](docs/images/version-history-restore.png)
54+
*Confirmation dialog before restoring a previous version*
55+
56+
### After Restore
57+
![After Restore](docs/images/version-history-restored.png)
58+
*New version created with "Restored from version X" summary*
59+
60+
## The 4-Tier Permission System
61+
62+
### Why Custom Tiers?
63+
64+
Pelican Panel has two built-in permission contexts:
65+
1. **Admin Panel** - Root admins and users with admin roles
66+
2. **Server Panel** - Server owners and subusers with granular permissions
67+
68+
However, for documentation, we needed more nuance. A game server host typically has:
69+
- **Infrastructure documentation** - Only for the hosting team (network configs, security policies)
70+
- **Server administration guides** - For server owners renting/managing servers
71+
- **Moderator handbooks** - For trusted users helping manage game servers
72+
- **Player-facing docs** - Rules, guides, and welcome messages for everyone
73+
74+
Pelican's native permissions don't map cleanly to these roles, so we created a **virtual permission tier system** that infers user roles from their existing Pelican permissions.
75+
76+
### Permission Tiers
77+
78+
| Tier | Badge | Who Can See | How It's Determined |
79+
|------|-------|-------------|---------------------|
80+
| **Host Admin** | 🔴 Red | Root Admins only | `user.isRootAdmin()` |
81+
| **Server Admin** | 🟠 Orange | Server owners + admins with Server Update/Create | Server ownership OR admin panel server permissions |
82+
| **Server Mod** | 🔵 Blue | Subusers with control permissions | Has `control.*` subuser permissions (start/stop/restart/console) |
83+
| **Player** | 🟢 Green | Anyone with server access | Default - anyone who can view the server |
84+
85+
### Hierarchy
86+
87+
Higher tiers see all documents at their level **and below**:
88+
- **Host Admin** sees: Host Admin, Server Admin, Server Mod, Player
89+
- **Server Admin** sees: Server Admin, Server Mod, Player
90+
- **Server Mod** sees: Server Mod, Player
91+
- **Player** sees: Player only
92+
93+
### Example Use Cases
94+
95+
| Document | Type | Global | Use Case |
96+
|----------|------|--------|----------|
97+
| Infrastructure Security Policy | Host Admin | Yes | Internal security guidelines for your hosting team |
98+
| Server Administration Guide | Server Admin | Yes | SOPs for anyone managing a server |
99+
| Moderator Handbook | Server Mod | Yes | Guidelines for trusted helpers with console access |
100+
| Welcome to Our Servers! | Player | Yes | Community rules visible to all players |
101+
| Minecraft Server Info | Player | No | Server-specific information for one server only |
102+
103+
## Installation
104+
105+
### Requirements
106+
- Pelican Panel v1.0+
107+
- PHP 8.2+
108+
109+
### Install via Admin Panel
110+
111+
1. Download the plugin zip or clone to your plugins directory
112+
2. Navigate to **Admin Panel → Plugins**
113+
3. Click **Install** next to "Server Documentation"
114+
4. Run migrations when prompted
115+
116+
### Manual Installation
117+
118+
```bash
119+
# Copy plugin to plugins directory
120+
cp -r server-documentation /var/www/html/plugins/
121+
122+
# Run migrations
123+
php /var/www/html/artisan migrate
124+
```
125+
126+
> **Note**: This plugin has no external composer dependencies - it uses Pelican's bundled packages only.
127+
128+
## Usage
129+
130+
### Creating Documents
131+
132+
1. Go to **Admin Panel → Documents**
133+
2. Click **New Document**
134+
3. Fill in:
135+
- **Title** - Display name for the document
136+
- **Slug** - URL-friendly identifier (auto-generated from title)
137+
- **Type** - Permission tier (Host Admin, Server Admin, Server Mod, Player)
138+
- **All Servers** - Toggle to show on every server
139+
- **Published** - Toggle to hide from non-admins while drafting
140+
- **Sort Order** - Lower numbers appear first in lists
141+
4. **Server Assignment** (if "All Servers" is disabled):
142+
- Optionally filter servers by **Egg** (game type)
143+
- Select servers using checkboxes
144+
- Use "Select All" / "Deselect All" for bulk selection
145+
5. Write your content using the rich text editor
146+
6. Click **Save**
147+
148+
### Attaching to Servers (After Creation)
149+
150+
You can also attach documents to servers after creation:
151+
152+
1. Edit the document
153+
2. Scroll to the **Servers** relation manager
154+
3. Click **Attach** and select servers
155+
4. Use drag-and-drop to reorder documents
156+
157+
Or from the server side:
158+
1. Go to **Admin Panel → Servers → [Server] → Documents tab**
159+
2. Click **Attach** and select documents
160+
3. Use drag-and-drop to reorder
161+
162+
### Importing Markdown
163+
164+
1. Go to **Admin Panel → Documents**
165+
2. Click **Import Markdown**
166+
3. Upload a `.md` file
167+
4. Optionally enable "Use YAML Frontmatter" to extract metadata:
168+
169+
```yaml
170+
---
171+
title: My Document
172+
slug: my-document
173+
type: player
174+
is_global: true
175+
is_published: true
176+
sort_order: 10
177+
---
178+
179+
# Document Content
180+
181+
Your markdown content here...
182+
```
183+
184+
### Exporting Documents
185+
186+
1. Edit any document
187+
2. Click the **Download** icon in the header
188+
3. Document downloads as `.md` with YAML frontmatter
189+
190+
### Version History
191+
192+
1. Edit any document
193+
2. Click the **History** icon (shows badge with version count)
194+
3. View previous versions with timestamps and editors
195+
4. Click **Preview** to see old content
196+
5. Click **Restore** to revert to a previous version
197+
198+
## Configuration
199+
200+
### Environment Variables
201+
202+
All settings can be configured via environment variables or by publishing the config file:
203+
204+
```bash
205+
# Cache Settings
206+
SERVER_DOCS_CACHE_TTL=300 # Cache TTL for document queries (seconds, 0 to disable)
207+
SERVER_DOCS_BADGE_CACHE_TTL=60 # Cache TTL for navigation badge count (seconds)
208+
209+
# Version History
210+
SERVER_DOCS_VERSIONS_TO_KEEP=50 # Max versions per document (0 = unlimited)
211+
SERVER_DOCS_AUTO_PRUNE=false # Auto-prune old versions on save
212+
213+
# Import Settings
214+
SERVER_DOCS_MAX_IMPORT_SIZE=512 # Max markdown import file size (KB)
215+
SERVER_DOCS_ALLOW_HTML_IMPORT=false # Allow raw HTML in imports (security risk)
216+
217+
# Permissions
218+
SERVER_DOCS_EXPLICIT_PERMISSIONS=false # Require explicit document permissions
219+
220+
# Audit Logging
221+
SERVER_DOCS_AUDIT_LOG_CHANNEL=single # Log channel for audit events
222+
```
223+
224+
### Admin Permissions
225+
226+
By default, users with server management permissions (`update server` or `create server`) can manage documents. Set `SERVER_DOCS_EXPLICIT_PERMISSIONS=true` to require explicit document permissions instead.
227+
228+
The plugin registers these Gates:
229+
230+
- `viewList document`
231+
- `view document`
232+
- `create document`
233+
- `update document`
234+
- `delete document`
235+
236+
To extend access to other admin roles, modify the `registerDocumentPermissions()` method in the ServiceProvider.
237+
238+
### Customization
239+
240+
The plugin uses Pelican's standard extensibility patterns:
241+
242+
```php
243+
// In another plugin or service provider
244+
use Starter\ServerDocumentation\Filament\Admin\Resources\DocumentResource;
245+
246+
// Modify the form
247+
DocumentResource::modifyForm(function (Form $form) {
248+
return $form->schema([
249+
// Add custom fields
250+
]);
251+
});
252+
253+
// Modify the table
254+
DocumentResource::modifyTable(function (Table $table) {
255+
return $table->columns([
256+
// Add custom columns
257+
]);
258+
});
259+
```
260+
261+
## File Structure
262+
263+
```text
264+
server-documentation/
265+
├── composer.json # PSR-4 autoloading (no external deps)
266+
├── config/server-documentation.php # Configuration options
267+
├── plugin.json # Plugin metadata
268+
├── database/
269+
│ ├── factories/ # Model factories for testing
270+
│ └── migrations/ # Database schema
271+
├── lang/en/strings.php # Translations (i18n ready)
272+
├── resources/
273+
│ ├── css/ # Document content styling
274+
│ └── views/filament/ # Blade templates
275+
├── tests/
276+
│ └── Unit/ # Unit tests (Pest)
277+
│ ├── Enums/
278+
│ ├── Models/
279+
│ ├── Policies/
280+
│ └── Services/
281+
└── src/
282+
├── Enums/ # DocumentType enum
283+
├── Models/ # Document, DocumentVersion
284+
├── Policies/ # Permission logic
285+
├── Providers/ # Service provider
286+
├── Services/ # DocumentService, MarkdownConverter
287+
└── Filament/
288+
├── Admin/ # Admin panel resources
289+
├── Concerns/ # Shared traits (HasDocumentTableColumns)
290+
└── Server/ # Server panel pages
291+
```
292+
293+
## Database Schema
294+
295+
```text
296+
documents
297+
├── id, uuid
298+
├── title, slug (unique)
299+
├── content (HTML from rich editor)
300+
├── type (host_admin, server_admin, server_mod, player)
301+
├── is_global, is_published
302+
├── sort_order
303+
├── author_id, last_edited_by
304+
├── timestamps, soft_deletes
305+
306+
document_versions
307+
├── id, document_id
308+
├── title, content (snapshot)
309+
├── version_number
310+
├── edited_by, change_summary
311+
├── created_at
312+
313+
document_server (pivot)
314+
├── document_id, server_id
315+
├── sort_order
316+
├── timestamps
317+
```
318+
319+
## Testing
320+
321+
The plugin includes comprehensive unit tests using Pest PHP:
322+
323+
```bash
324+
# Run all tests
325+
cd /path/to/pelican-panel
326+
php artisan test --filter=ServerDocumentation
327+
328+
# Run specific test file
329+
php artisan test plugins/server-documentation/tests/Unit/Services/DocumentServiceTest.php
330+
331+
# Run with coverage
332+
php artisan test --filter=ServerDocumentation --coverage
333+
```
334+
335+
### Test Coverage
336+
337+
- **DocumentService** - Version creation, caching, permission checks
338+
- **MarkdownConverter** - HTML↔Markdown conversion, sanitization, frontmatter
339+
- **DocumentType Enum** - Hierarchy levels, visibility, options
340+
- **DocumentPolicy** - Authorization for admin and server panel
341+
- **Document Model** - Events, scopes, relationships
342+
343+
## Contributing
344+
345+
This plugin was developed for [Pelican Panel](https://pelican.dev). Contributions welcome!
346+
347+
1. Fork the repository
348+
2. Create a feature branch
349+
3. Make your changes
350+
4. Run tests: `php artisan test --filter=ServerDocumentation`
351+
5. Submit a pull request
352+
353+
## License
354+
355+
MIT License - see [LICENSE](LICENSE) for details.
356+
357+
## Credits
358+
359+
- Built for [Pelican Panel](https://pelican.dev)
360+
- Uses Pelican's bundled [League CommonMark](https://commonmark.thephpleague.com/) for Markdown→HTML parsing
361+
- Built-in HTML→Markdown converter for exports (no external dependencies)
362+

0 commit comments

Comments
 (0)