# Realms and spells

> Create realms, import or write spells, set the default Docker image, add variables and control the order users see when they pick a spell.

Source: https://featherpanel.com/docs/admin/realms-and-spells/

Realms are categories and spells are the server templates inside them. A user picks a realm and a spell when a server
is created, so set these up before you create servers. What a spell contains is described in
[Spells (eggs)](https://featherpanel.com/docs/spells).

## Realms

Admin area, Realms. A realm has a name and a description, nothing more. Use one per game or app type. A realm cannot be
deleted while spells or servers are assigned to it.

## Spells

Admin area, Spells lists every spell. Open a realm to see only its spells ("Managing spells for realm"). From here you
can:

- **Create Spell.** Fill in the General, Docker, Features, Config and Script tabs.
- **Import Spell.** Choose the realm and upload a Pterodactyl or FeatherPanel JSON file.
- **Browse Marketplace.** Opens the Spells Marketplace to install community eggs.
- **Reorder spells.** Use the arrows to set the order inside a realm. This is the order shown when someone picks a
  spell.
- **Export** a spell as JSON, or **Delete** it. Deleting fails while servers use the spell or other spells inherit
  from it.

### Editing a spell

| Tab | Settings |
| --- | --- |
| General | Name, author, description, update URL, banner URL. |
| Docker | Docker images. Click the star on the image that new servers should get by default, and update it when runtimes change, for example a newer Java version. Script container, script entry, Force outgoing IP. |
| Features | Feature tags, or inherit them from another spell. |
| Config | File denylist, config files, startup and logs (JSON), stop command, inherit configuration from another spell. |
| Script | Install script, Privileged or Non-privileged, startup command, copy the installation script from another spell. |
| Variables | Shown after the spell exists. Name, env variable, description, default value, field type, validation rules, User Viewable and User Editable. |


## Where else spells show up

- **Mounts** can be limited to certain spells.
- **Plugins** can be hidden from the server sidebar for some spells (Plugins, a plugin, Spells tab).
- **Global Subdomains** lists the spells a subdomain domain applies to.
- **Servers** can be switched to another realm, spell or Docker image on the Application tab of Edit Server.

## API

| Method | Path | Permission |
| --- | --- | --- |
| GET | `/api/admin/realms` | admin.realms.view |
| PUT | `/api/admin/realms` | admin.realms.create |
| PATCH, DELETE | `/api/admin/realms/{id}` | admin.realms.edit, admin.realms.delete |
| GET | `/api/admin/spells`, `/api/admin/spells/realm/{realmId}` | admin.spells.view |
| PUT | `/api/admin/spells` | admin.spells.create |
| POST | `/api/admin/spells/import` | admin.spells.create |
| GET | `/api/admin/spells/{id}/export` | admin.spells.view |
| POST | `/api/admin/spells/reorder` | admin.spells.edit |
| GET, POST | `/api/admin/spells/{spellId}/variables` | admin.spells.view, admin.spells.edit |
| GET, POST | `/api/admin/spells/online/list`, `/api/admin/spells/online/install` | admin.spells.view, admin.spells.create |

The full list is in the [API reference](https://featherpanel.com/docs/api/reference).

## Frequently asked questions

### Why can I not delete a realm?

The panel refuses while the realm still has spells or servers. Move or delete them first.

### Which permissions do I need?

The pages need admin.realms.view. Changing spells needs admin.spells.create, admin.spells.edit or admin.spells.delete, and realms have the matching admin.realms permissions.