Creating Custom Spells

This guide walks you through the complete process of creating custom spells in FeatherPanel, from initial setup to deployment.

Prerequisites

Before creating a spell, ensure you have:

Admin access to FeatherPanel
Docker knowledge for container management
Understanding of the target application you're creating a spell for
Basic scripting knowledge for entrypoint scripts

Step 1: Create New Spell

Using the Admin Interface

Navigate to Spells
- Go to Admin → Spells
- Click "Create New Spell"
Basic Information
- Spell Name: Descriptive name (e.g., "Minecraft Forge")
- Description: Brief description of what the spell does
- Author: Your name or organization
- Version: Starting version (e.g., "1.0.0")
Docker Configuration
- Docker Image: Full image name (e.g., ghcr.io/featherpanel/minecraft-forge:latest)
- Startup Command: Command to start the server
- Stop Command: Command to safely stop the server

Example Basic Configuration

{
  "name": "Minecraft Forge Server",
  "description": "Minecraft server with Forge modloader support",
  "docker_image": "ghcr.io/featherpanel/minecraft-forge:latest",
  "startup": "java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}} --nogui",
  "stop": "stop"
}

Step 2: Configure Process Management

Stop Command Configuration

The stop command tells FeatherPanel how to safely stop your server:

{
  "stop": "stop"
}

Common Stop Commands:

stop - Standard Minecraft stop command
end - Alternative stop command
^C - Send SIGINT signal (Ctrl+C)
quit - Application-specific quit command
exit - Simple exit command

Log Storage Configuration

Configure how logs are handled:

{
  "logs": "{}"
}

Logs are handled by the daemon using Docker logs to output complete server output.

Configuration Files

Define which files to parse and modify before server startup:

{
  "config_files": {
    "server.properties": {
      "parser": "properties",
      "find": {
        "server-ip": "0.0.0.0",
        "enable-query": "true",
        "server-port": "{{SERVER_PORT}}",
        "query.port": "{{SERVER_PORT}}"
      }
    }
  }
}

Supported Parsers

Properties Parser

{
  "server.properties": {
    "parser": "properties",
    "find": {
      "server-port": "{{SERVER_PORT}}",
      "max-players": "{{MAX_PLAYERS}}"
    }
  }
}

YAML Parser (supports wildcards)

{
  "config.yml": {
    "parser": "yaml",
    "find": {
      "server.port": "{{SERVER_PORT}}",
      "listeners[0].query_port": "{{SERVER_PORT}}",
      "servers.*.address": {
        "127.0.0.1": "{{config.docker.interface}}",
        "localhost": "{{config.docker.interface}}"
      }
    }
  }
}

JSON Parser (supports wildcards)

{
  "config.json": {
    "parser": "json",
    "find": {
      "server.port": "{{SERVER_PORT}}",
      "plugins.*.enabled": true
    }
  }
}

INI Parser

{
  "config.ini": {
    "parser": "ini",
    "find": {
      "server.port": "{{SERVER_PORT}}",
      "server.host": "0.0.0.0"
    }
  }
}

XML Parser

{
  "config.xml": {
    "parser": "xml",
    "find": {
      "server.port": "{{SERVER_PORT}}",
      "server.host": "0.0.0.0"
    }
  }
}

Start Configuration

Define when the server is ready for players:

{
  "start_config": {
    "done": ")! For help, type "
  }
}

This tells FeatherPanel what output indicates the server is ready.

Step 3: Copy Settings From

You can copy settings from existing spells to avoid duplicating configuration:

{
  "copy_settings_from": "minecraft-vanilla"
}

Benefits:

Inherit common settings from parent spell
Override specific settings as needed
Maintain consistency across similar spells
Reduce configuration duplication

Limitations:

No nested copying - only one level deep
Parent must not copy from another spell
Override takes precedence over inherited settings

Step 4: Define Spell Variables

Spell variables allow users to customize server settings without modifying the startup command.

Creating Variables

Navigate to Variables Tab
Click "Add Variable"
Configure Variable Settings

Variable Configuration

{
  "name": "Server JAR File",
  "description": "The JAR file to run for the server",
  "env_variable": "SERVER_JARFILE",
  "default_value": "forge-server.jar",
  "user_viewable": true,
  "user_editable": true,
  "rules": "required|string|between:1,255"
}

Variable Properties

Name: Display name for the variable
Description: Help text for users
Environment Variable: Variable name (uppercase, alphanumeric + underscores)
Default Value: Default value if not set
User Viewable: Can users see this variable?
User Editable: Can users modify this variable?
Rules: Validation rules (Laravel validation)

Variable Types

String Variables

{
  "name": "World Name",
  "env_variable": "WORLD_NAME",
  "default_value": "world",
  "rules": "required|string|between:1,32"
}

Numeric Variables

{
  "name": "Max Players",
  "env_variable": "MAX_PLAYERS",
  "default_value": "20",
  "rules": "required|integer|min:1|max:100"
}

Boolean Variables

{
  "name": "Enable PvP",
  "env_variable": "ENABLE_PVP",
  "default_value": "false",
  "rules": "required|boolean"
}

Select Variables

{
  "name": "Difficulty",
  "env_variable": "DIFFICULTY",
  "default_value": "normal",
  "rules": "required|in:peaceful,easy,normal,hard"
}

Using Variables

Variables can be used in:

Startup Commands

java -Xms128M -Xmx{{SERVER_MEMORY}}M -jar {{SERVER_JARFILE}}

Configuration Files

{
  "server.properties": {
    "parser": "properties",
    "find": {
      "max-players": "{{MAX_PLAYERS}}",
      "level-name": "{{WORLD_NAME}}"
    }
  }
}

Environment Variables

export SERVER_NAME="{{SERVER_NAME}}"
export MAX_PLAYERS="{{MAX_PLAYERS}}"

Step 5: Advanced Configuration

File Denylist

Exclude files from backups and transfers:

{
  "file_denylist": [
    "*.log",
    "*.tmp",
    "cache/",
    "logs/",
    "*.pid"
  ]
}

Installation Script

Define installation steps for new servers:

{
  "install_script": {
    "entrypoint": "install.sh",
    "container": "ghcr.io/featherpanel/installer:latest"
  }
}

Resource Limits

Set default resource limits:

{
  "resource_limits": {
    "memory": 1024,
    "cpu": 100,
    "disk": 5120,
    "io": 1000
  }
}

Step 6: Testing Your Spell

1. Create Test Server

Navigate to Servers
Click "Create New Server"
Select your spell from the dropdown
Configure server settings
Create the server

2. Test Server Functionality

Start the server and monitor logs
Verify configuration files are parsed correctly
Test variable replacement in commands and files
Check server connectivity and functionality
Test stop/start procedures

3. Validate Configuration

Check file permissions and ownership
Verify environment variables are set correctly
Test backup/restore functionality
Validate resource limits are enforced
Check log output for errors

Step 7: Deployment

1. Export Spell

Navigate to your spell
Click "Export"
Download spell file
Test import on another instance

2. Distribute Spell

Share spell file with other administrators
Upload to spell repository (if available)
Document spell usage and requirements
Provide support for spell users

3. Version Management

Version your spells using semantic versioning
Document changes in version notes
Test updates before distribution
Maintain backward compatibility when possible

Best Practices

Spell Design

Use descriptive names and descriptions
Provide clear documentation for users
Set sensible defaults for all variables
Validate user input with appropriate rules
Test thoroughly before distribution

Docker Images

Use official base images when possible
Minimize image size with multi-stage builds
Follow security best practices (non-root user)
Include necessary dependencies only
Document image requirements clearly

Configuration

Use appropriate parsers for file types
Validate configuration before applying
Handle missing variables gracefully
Provide fallback values for optional settings
Test file parsing with various configurations

Variables

Use descriptive variable names and descriptions
Set appropriate validation rules for each variable
Provide helpful default values
Group related variables logically
Document variable usage and effects

Testing

Test on clean systems to ensure dependencies
Verify all file types are parsed correctly
Test edge cases and error conditions
Validate resource usage and limits
Check compatibility with different FeatherPanel versions

Troubleshooting

Common Issues

Spell Not Loading

Check spell JSON syntax
Verify Docker image exists
Ensure all required fields are present
Check file permissions

Configuration Not Applied

Verify file parser is correct
Check variable names match exactly
Ensure files exist in container
Validate JSON syntax in config_files

Server Not Starting

Check startup command syntax
Verify all variables are defined
Check Docker image compatibility
Review container logs for errors

Variables Not Working

Ensure variable names are uppercase
Check validation rules are correct
Verify default values are set
Test variable replacement manually

Debugging Tips

Enable debug logging in FeatherPanel
Check container logs for detailed errors
Test variable replacement manually
Validate file parsing with sample files
Use Docker exec to inspect running containers

This comprehensive guide should help you create robust, well-tested spells for FeatherPanel that provide a great user experience and reliable server management.

Creating Custom Spells

On this page

MythicalFM Romanian