docs: Add Scroll system documentation (#28)

druid-infra · Lugh (Druid Bot) · web-flow · commit fabe5cb38c29 · 2026-02-10T16:16:30.000+01:00
* docs: Add comprehensive Scroll system documentation

- Explain Scroll concept (OCI artifacts for deployment)
- Document scroll.yaml format and all fields
- Provide examples for 95+ game servers
- Detail command system and procedures
- Cover ColdStarter integration
- Document plugin system
- Include best practices and contribution guidelines
- Add troubleshooting and advanced topics

* fix: Remove broken internal links

- Replace Next Steps section with external GitHub links
- Fixes broken link errors for files that don't exist yet

* docs: Emphasize complete freedom in command naming

- Add prominent section explaining command names are 100% customizable
- No required names (start, stop, install are just conventions)
- Show multiple examples with custom names (launch, halt, setup, etc.)
- Add FAQ clarifying this freedom
- Update all command references to emphasize customization

* docs: Document Nix integration as dependency system

- Remove generic 'built-in dependencies' list
- Add comprehensive Nix section explaining why/how it works
- Explain isolation, reproducibility, 80k+ package library
- Show real-world examples (multi-version Java)
- Explain Nix store, caching, and performance benefits
- Emphasize Nix as foundational to Druid architecture
- Link to nixpkgs search for package discovery

* docs: Fix scroll creation workflow and commands

- Replace 'Fork the Repository' with 'Find Examples' linking to scrolls repo
- Remove incorrect commands: druid scroll build, druid scroll deploy, druid start
- Add correct commands: druid scroll validate, druid serve, druid run &lt;command&gt;
- Remove 'Publish to Registry' section (maintainer-only workflow)
- Verified against druid-cli source code

* docs: Fix procedure modes table with actual modes from source

- Verified all modes from druid-cli source code
- Removed incorrect modes: signal, http, write (don't exist)
- Added actual modes: exec, exec-tty, stdin, scroll-switch, rcon, command
- Added correct data formats for each mode
- Note about plugin-provided modes

* docs: Remove common dependencies examples from Nix section

- Removed package list from Dependencies subsection
- Removed package examples from Available Packages subsection
- Keep Nix section generic, just point to nixpkgs search
- Users can discover packages themselves at search.nixos.org

* docs: Cut Scroll System by 60% - verified all commands against source

- Reduced from 665 to 260 lines
- Verified druid scroll validate, druid serve, druid run against CLI source
- Verified procedure modes: exec, exec-tty, stdin, scroll-switch, rcon, command
- Verified scroll.yaml field names against domain/scroll.go
- Removed repetitive examples and fluff
- Keep only essential information

---------

Co-authored-by: Lugh (Druid Bot) &lt;lugh@druid.gg&gt;
diff --git a/docs/scrolls/_category_.json b/docs/scrolls/_category_.json
@@ -0,0 +1,5 @@
+{
+  "label": "Scroll System",
+  "position": 7,
+  "collapsed": false
+}
diff --git a/docs/scrolls/introduction.md b/docs/scrolls/introduction.md
@@ -0,0 +1,294 @@
+---
+sidebar_position: 1
+title: Scroll System
+description: Declarative deployment packages for Druid
+---
+
+# Scroll System
+
+Scrolls are OCI artifacts that define how to deploy and manage applications on Druid. Like Kubernetes Helm charts, but for game servers.
+
+## What's in a Scroll?
+
+```
+scrolls/minecraft/papermc/1.21.7/
+├── scroll.yaml              # Main manifest
+├── start.sh                 # Start script
+├── packet_handler/
+│   └── minecraft.lua        # ColdStarter handler
+└── plugins/
+    └── rcon.yaml            # RCON plugin
+```
+
+## Command Names
+
+Command names in `scroll.yaml` are **completely customizable**. No required names - use whatever makes sense:
+
+```yaml
+init: "launch"       # Not "start"
+
+commands:
+  launch:            # Your choice
+    procedures:
+      - mode: exec
+        data: [./server]
+  
+  halt:              # Not "stop"
+    procedures:
+      - mode: stdin
+        data: [launch, stop]
+```
+
+Names like `start`, `stop`, `install` are just conventions.
+
+## scroll.yaml Format
+
+### Minimal Example
+
+```yaml
+name: artifacts.druid.gg/my-org/my-game
+desc: My Game Server
+version: 1.0.0
+app_version: 2024.1
+
+ports:
+  - name: game
+    protocol: tcp
+    port: 7777
+
+init: "start"
+
+commands:
+  start:
+    procedures:
+      - mode: exec
+        data: [./game-server, --port=7777]
+```
+
+### Complete Example
+
+```yaml
+name: artifacts.druid.gg/druid-team/scroll-minecraft-paper
+desc: PaperMC High-Performance Minecraft Server
+version: 0.0.1
+app_version: 1.21.7
+
+ports:
+  - name: main
+    protocol: tcp
+    port: 25565
+    sleep_handler: packet_handler/minecraft.lua
+    start_delay: 10
+    finish_after_command: install
+  
+  - name: rcon
+    protocol: tcp
+    port: 25575
+
+init: "start"
+
+commands:
+  start:
+    needs: [install]
+    run: restart
+    dependencies: [jdk21]
+    procedures:
+      - mode: exec
+        data: [bash, ./start.sh]
+  
+  stop:
+    procedures:
+      - mode: rcon
+        data: stop
+  
+  install:
+    run: once
+    dependencies: [wget, cacert]
+    procedures:
+      - mode: exec
+        data:
+          - wget
+          - -O
+          - paper.jar
+          - https://api.papermc.io/v2/projects/paper/versions/1.21.7/builds/latest/downloads/paper-1.21.7.jar
+      
+      - mode: exec
+        data: [bash, -c, 'echo eula=true > eula.txt']
+
+plugins:
+  rcon: {}
+```
+
+## Field Reference
+
+### Top-Level
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | ✅ | OCI artifact name |
+| `desc` | string | ✅ | Description |
+| `version` | string | ✅ | Scroll version (semver) |
+| `app_version` | string | ✅ | Application version |
+| `ports` | array | ✅ | Port definitions |
+| `init` | string | ✅ | Initial command (your custom name) |
+| `commands` | object | ✅ | Command definitions |
+| `plugins` | object | ❌ | Plugin configs |
+
+### Port
+
+```yaml
+- name: game                    # Port identifier
+  protocol: tcp                 # tcp | udp
+  port: 25565                   # Port number
+  sleep_handler: handler.lua    # ColdStarter handler (optional)
+  start_delay: 10               # Seconds before ready (optional)
+  finish_after_command: install # Enable after command (optional)
+  check_activity: true          # Monitor for idle (optional)
+```
+
+### Command
+
+```yaml
+command_name:                   # Freely choose any name
+  needs: [other_command]        # Prerequisites (optional)
+  run: restart                  # once | always | restart (optional)
+  dependencies: [jdk21, wget]   # Nix dependencies (optional)
+  procedures:                   # Steps to execute
+    - mode: exec                # Execution mode
+      data: [bash, script.sh]   # Mode-specific data
+```
+
+### Procedure Modes
+
+| Mode | Description | Data Format |
+|------|-------------|-------------|
+| `exec` | Execute command | `string[]` - Command + args |
+| `exec-tty` | Execute with TTY | `string[]` - Command + args |
+| `stdin` | Write to process stdin | `string[2]` - `[process_name, stdin_data]` |
+| `scroll-switch` | Switch to another scroll | `string` - OCI artifact name |
+| `rcon` | RCON command (plugin) | `string` - Command to send |
+| `command` | Run another command (deprecated) | `string` - Command name |
+
+**Note:** Plugins can provide additional modes (e.g., `rcon_web_rust`).
+
+### Dependencies
+
+Druid uses **Nix** for dependency management. This provides:
+
+- ✅ **Reproducible environments** - Same dependencies everywhere
+- ✅ **Isolation** - No conflicts between scrolls
+- ✅ **Declarative** - Dependencies defined in scroll.yaml
+- ✅ **Massive package library** - 80,000+ packages from nixpkgs
+
+**Any package from [nixpkgs](https://search.nixos.org/packages)** can be used as a dependency.
+
+## Creating Your Own Scroll
+
+### Find Examples
+
+Browse the [scrolls repository](https://github.com/highcard-dev/scrolls) for examples.
+
+### Step 1: Create scroll.yaml
+
+```yaml
+name: artifacts.druid.gg/my-org/my-game
+desc: My Game Server
+version: 1.0.0
+app_version: 1.0.0
+
+ports:
+  - name: game
+    protocol: tcp
+    port: 7777
+
+init: "start"
+
+commands:
+  start:
+    dependencies: [wget]
+    procedures:
+      - mode: exec
+        data: [./game-server, --port=7777]
+```
+
+### Step 2: Validate and Test
+
+```bash
+# Validate scroll syntax
+druid scroll validate
+
+# Start the server
+druid serve
+
+# Or run specific command
+druid run start
+```
+
+## Nix Integration
+
+Nix is **foundational** to Druid's architecture.
+
+### Why Nix?
+
+- Multiple versions coexist (jdk8 + jdk21 simultaneously)
+- Isolated environments per scroll
+- Reproducible builds
+- 80,000+ packages available
+
+### How It Works
+
+```yaml
+commands:
+  start:
+    dependencies: [jdk21, wget, git]
+    procedures:
+      - mode: exec
+        data: [java, -jar, server.jar]
+```
+
+Druid:
+1. Resolves dependencies from nixpkgs
+2. Downloads exact versions (or uses cache)
+3. Builds isolated environment
+4. Executes commands in that environment
+
+### Finding Packages
+
+Search at: https://search.nixos.org/packages
+
+Example:
+
+```yaml
+# Need Mono for C# game server?
+dependencies: [mono]
+```
+
+### Multi-Version Example
+
+Run Minecraft 1.12 (Java 8) and 1.21 (Java 21) simultaneously:
+
+**Scroll 1 (Minecraft 1.12):**
+```yaml
+dependencies: [jdk8]
+```
+
+**Scroll 2 (Minecraft 1.21):**
+```yaml
+dependencies: [jdk21]
+```
+
+No conflicts - each gets its own Java version.
+
+## Supported Games
+
+95 published scrolls:
+- 81 Minecraft variants
+- 2 Rust (Vanilla, Oxide)
+- 2 Hytale
+- 10 LGSM games (Palworld, ARK, CS2, etc.)
+
+## Learn More
+
+- [Scrolls Repository](https://github.com/highcard-dev/scrolls)
+- [Druid CLI](https://github.com/highcard-dev/druid-cli)
+- [Nix Packages](https://search.nixos.org/packages)
