Pelican

Sell game servers from your Pelican panel and let customers run them entirely from your Blesta client area.

What it does

Selling game servers usually means creating panel accounts by hand, hunting for free ports for games that need several of them, and sending customers off to a second control panel for everything they want to change. The Pelican module creates the panel account and the server when an order is paid, places it on a node with room, reserves every port the game needs on one IP, and fills in the egg's settings. Your customers then manage the server from your client area: console, files, databases, backups, schedules, ports, users, startup settings, reinstall and activity are all there.

Key features

• Automatic Server Lifecycle: A paid order creates the panel account and the game server, and suspensions, unsuspensions, package changes and cancellations follow on the panel without anyone opening it.
• Any Egg, Any Game: Pick the egg on the package and its startup command, Docker image and variables come straight from the panel.
• Multi-Port Games Done Right: Reserve extra ports per game as offsets or ranges on the same IP, with spare ports and an optional port range.
• Game Picker in One Click: Build a Game Server list and each egg's variables as configurable options with show-when-picked logic in one step.
• Full Client Area Control: Overview with live stats and power, Console, Files, Databases, Backups, Schedules, Network, Users, Startup, Settings and Activity tabs.
• Clear Order Checks: Orders missing a required game setting are stopped with a clear message, and a failed order never leaves a half-created server.
• Staff Overview Tab: Suspend, unsuspend or reapply the package resources from the service page.
• Built-In Demo Mode: Try every screen and action with bundled sample data before you connect a panel.

Installing Pelican

Before you start

• Requires Blesta 6.0 or later.
• If you are on the leased (subscription) licence, the Blesta Club Subscription Manager must be installed and your subscription active. The owned and owned-source licences have no such requirement.
• To provision real servers you need a Pelican panel with two API keys (see The two API keys). To try the module first you need neither: the built-in Mock API mode runs every screen and action from bundled sample data.

1. Upload the files

Upload the extension folder into your Blesta installation so it lands under your Blesta directory at:

components/modules/pelican/

For example, on a typical install: /var/www/html/blesta/components/modules/pelican/

2. Install it in Blesta

1. Log in to your Blesta admin area with a staff account that has the Modules permission under the Settings group in Manage Staff Groups.
2. Go to Settings > Company > Modules and click the Available tab.
3. Find Pelican in the list and click Install.

3. Configure it

1. Under the Installed tab, click Manage next to Pelican.
2. Click Add Panel and fill in:
   • Name - a label for this panel, shown in the panel list.
   • Panel URL - the address of your Pelican panel, for example https://panel.example.com, with no path.
   • Application API Key - an application key (starts with papp_).
   • Admin Account API Key - the account key of a root administrator (starts with pacc_).
   • Enable Mock API - leave unticked for a real panel. Tick it to run the module from built-in sample data; no keys are checked.
3. Save the panel. Unless Mock API is ticked, Blesta checks both keys with the panel as you save and refuses the panel if either fails.
4. On each node, make the console work: allow your Blesta site in the Wings allowed origins, make the node reachable from the internet and serve it over https. See Console requirements.
5. Create a package on this module and open its Module tab: pick the Egg, choose Placement by node tags or on selected nodes, set the resource limits, and fill in or show to the customer the egg variables listed below the limits. The usage guide explains every field.

You're ready to go - see the usage guide for a walkthrough of day-to-day use.

The two API keys

A panel row needs two different keys. They look alike, they come from different pages of the panel, and they are not interchangeable. Pasting each one into the other's field is an easy mistake to make, and the panel will not save until each key is in its own field.

Check the prefix before you paste: papp_ goes in Application API Key, pacc_ goes in Admin Account API Key.

• The application key needs read and write access on users, servers, nodes (including allocations) and eggs.
• The account key must belong to a user with the root administrator flag, otherwise the client area tabs cannot reach other customers' servers. Create it while logged in as that user.
• Pelican shows a full key once, when you create it. The key list afterwards shows only the first characters, so copy the whole value from the creation dialog. A key cut short there is rejected as unauthenticated.
• Leave a key field blank when editing a panel to keep the stored value.

If the panel will not save

Saving a panel makes two read-only requests: a list of nodes with the application key, and a permissions lookup with the account key. If either fails you get "The panel could not be reached or a key was rejected."

Open Tools > Logs > Module. Each request is logged with the panel's answer (key values are masked):

If a client sees "This server could not be confirmed as yours on the panel"

The client tabs only manage a server whose owner on the panel is the client's own panel account. This usually happens after staff attached an existing server to a service: check that the service has both the Server ID and the Server UUID of that server, and that the server's owner on the panel uses the same email address as the client in Blesta. Change the owner on the panel (or the service's Server ID and UUID) and reload the tab.

Console requirements

The console connects each customer's browser straight to the node that runs their server, not through Blesta. Three things on every node must be true, or the console stays on "Disconnected" and the browser reports an error such as NS_ERROR_WEBSOCKET_CONNECTION_REFUSED. The panel row form in Blesta shows the same warning.

1. Allow this site. Add your Blesta site to allowed_origins in the node's Wings config.yml (usually /etc/pelican/config.yml), then restart Wings. Use the scheme and host exactly as customers see them, with no trailing slash, for example https://billing.example.com (add the port if it is not 443). Pelican only lists its own address there by default, so Blesta is rejected until you add it.
2. Make the node reachable. The node's FQDN and websocket port (8080 by default) must be reachable from customers' browsers over the internet. A private address such as 192.168.1.8 only works on that network.
3. Serve it over https. Blesta runs on https, and browsers refuse an unencrypted ws:// socket from an https page. Give the node a certificate (scheme https) or put it behind a reverse proxy.

To see what the panel hands the browser, open Tools > Logs > Module and find the websocket request for the server: its socket value is the exact address the browser connects to. To tell a rejected origin from a blocked port, open the Console tab with the browser developer tools Network tab on WS: a 403 on the handshake means the origin is not allowed, no response at all means the address or port cannot be reached.

Updating Pelican

Upgrading works just like installing: upload the new files over the old ones, then run the upgrade from the same page you installed it on.

1. Back up your current extension files first - good practice before any upgrade.
2. Upload the new version over the existing folder, replacing the old files.
3. Log in to your Blesta admin area and go to Settings > Company > Modules.
4. Find Pelican and click Update to run the upgrade.

This upgrade is drop-in - no steps are needed beyond replacing the files and clicking Update. Version 1.0.0 is the first release.

Using Pelican

For your staff

Adding a panel

Go to Settings > Company > Modules, open the Installed tab and click Manage next to Pelican. The Panels tab lists your Pelican panels; click Add Panel, enter a Name, the Panel URL, the Application API Key and the Admin Account API Key, and save. The form repeats the node settings the console needs (allowed origins, a reachable address, https). Tick Enable Mock API to try the module with sample data instead of a real panel. When you edit a panel, the two key fields stay blank; leaving them blank keeps the stored keys. The Panel Groups tab groups several panels so a package can use the first one in the group.

Configuring a package

On a package's Module tab:

• Egg - the game the server runs. Changing it reloads the egg's variables at the bottom of the form.
• Placement - By node tags (enter one or more comma separated Node Tags; any node carrying a tag and with room qualifies) or On selected nodes (select one or more Nodes in the list, holding Ctrl or Cmd to pick several; the one with the most free memory is tried first).
• Memory (MB), Swap (MB), Disk (MB), Block I/O Weight, CPU Limit (%) and CPU Pinning - the server's resource limits.
• Database Limit, Allocation Limit and Backup Limit - what the customer may create. The allocation limit is raised automatically to the number of ports the package reserves.
• Additional Port Configuration (Optional) - one line per extra port (see Ports below).
• Port Range (Optional) - keeps the primary, offset and spare ports inside one range, for example 8211-8300.
• Spare Ports - extra ports reserved on the same IP after the highest offset, for the customer to use.
• Docker Image and Startup Command - optional overrides of the egg defaults.
• Enable OOM Killer, Skip Egg Install Script and Start After Install.
• One field per egg variable, filled with the egg default. Tick Show ... to the customer next to a variable to let the customer set it when ordering; otherwise the package value (or the egg default) is used. A required variable with no default must either have a value here, be shown to the customer, or be filled by a port line; the package will not save otherwise.

Ports

Additional Port Configuration takes one line per extra port: QUERY_PORT|+1 assigns the primary port plus one, RCON_PORT|20010-20110 assigns a free port from the range. The port number is written into the egg variable the line names. All ports are on the same IP, and if a neighbouring port is taken the whole group moves up to the next block that fits. Start a line with an egg id and a colon (3: SERVER_COMM_PORT|+2) to apply it only when that egg is chosen. Two lines for the same egg cannot ask for the same offset.

Port Range limits the primary port, its offset ports and the spare ports. Lines that carry their own range (RCON_PORT|20010-20110) are not limited by it. Leave it empty to use any free port on the node. When no node has a free block, the order is refused and nothing is created on the panel.

Letting customers choose the game

Go to Settings > Company > Modules > Installed > Pelican > Manage, then the Configurable Options tab. Pick the panel and click Load Eggs. The table lists each egg with its variable count (required with no default / all). Enter an Option Group Name, choose whether to add only the variables that are required with no default or all variables, tick the eggs and the Packages to attach the group to, and click Build Options. This creates a Game Server list plus, for each egg, its variables, shown only when that egg is picked and priced at 0 for the terms of the ticked packages. Run it again to add eggs; nothing is deleted. Tick Hidden to keep the generated options out of the admin lists.

Ordering and editing a service

When a client orders, the module finds the client's panel account by email (or creates one), reserves the ports, and creates the server. The order is stopped with a message listing the required egg variables that have no value ("These egg variables are required and have no value: ..."), and a value that breaks the egg's rules is refused as "... is not valid". On the staff Add Service form every egg variable is listed. After choosing the package and term, wait for the form to refresh before picking a Game Server (egg) option, or the egg choice is reset by the refresh. To attach a server that already exists on the panel instead of creating one, untick provisioning and enter both its Server ID and its Server UUID (both are required). The server must belong to the client's own panel account, the one with the same email address as the client in Blesta; otherwise the client tabs refuse to manage it and show "This server could not be confirmed as yours on the panel". Editing a service renames the server and resizes it to the package limits. Changing a client's package resizes the server to the new package.

Service details

Expand the service's row in the client's Services list in the admin area (or, for the client, in their own Services list) to see the server name, its address (the port's alias when it has one), and the panel email, password and an Open Panel link.

The staff Overview tab

Open a service and its Overview tab to see the server name, address, status, CPU, memory and disk limits and its allocations, plus the client's panel email and password and an Open Panel button. Suspend or Unsuspend the server on the panel, or Reapply Package Resources to resize it to the current package limits.

For your clients

Overview

Shows the server name, a live status badge, its addresses, and CPU, memory, disk, network and uptime figures that refresh every few seconds. Start, Restart, Stop and Kill send power signals. The Panel Access box shows the panel email and password, and Open Panel opens the Pelican panel.

Console

A live console of the server with the same power buttons and a command box. It connects straight to the node, which must allow your Blesta site (see the install guide).

Files

Browse folders, open and edit text files and save them, create folders, upload files, rename, download, delete, compress the ticked files into an archive, and extract an archive with Extract. A failed upload names the file that failed.

Databases

Create a database with a name and the hosts allowed to connect, see its host, username and password, rotate the password or delete it, up to the package's database limit.

Backups

Create a backup with an optional name, files to leave out and a lock. Each backup can be downloaded, renamed, locked or unlocked, restored (after confirming the restore, a second prompt asks whether to delete all files on the server first) or deleted. Locked backups cannot be deleted. The backup limit comes from the package.

Schedules

Create a schedule with a name, the minute, hour, day, month and weekday, and whether it is active and runs only while the server is online. Each schedule can be run now, switched on or off, or deleted, and takes tasks: send a command, a power action or create a backup, with an offset in seconds.

Network

Lists the server's ports. Add an allocation (up to the package limit), make one primary, save notes on each, or remove a port that is not primary.

Users

Give another person access to the server by email, choosing permission groups such as console and power, files, backups or databases, and remove them again.

Startup

Shows the startup command, lets the customer switch between the egg's Docker images, and edit the variables the package exposes to them.

Settings

Shows the SFTP host and username, and lets the customer rename the server, set its description, or reinstall it.

Activity

Lists recent panel activity on the server with the time of each event. The IP address is shown only for actions taken by the customer's own panel account.

Good to know

• Configurable options by name: an option named egg_id, memory, swap, disk, io, cpu, threads, databases, allocations, backups, spare_ports, docker_image or startup overrides that package setting. An option named after an egg variable in lowercase (minecraft_version) sets it for any egg, and egg<ID>_<variable> (egg3_server_name) sets it only while egg <ID> is chosen. Values are checked against the egg's own rules before the order is accepted.
• One panel account per client: each client gets a single panel account per panel, reused for every server they buy.
• The admin account key is powerful: it reaches every server on the panel, so keep it private. It is never an email tag.
• Email tags: the welcome email can use {service.name}, {service.primary_ip}, {service.primary_alias}, {service.primary_port} and {module.url}; the default template shows the alias when the port has one.
• Module log: every panel request is logged under Tools > Logs > Module with keys, passwords and secret egg variables masked.
• Mock mode: with Enable Mock API ticked on a panel, ordering, every tab and every action run against built-in sample data; uploads and downloads stay inside your Blesta site, and an upload over 512 KB is refused to show the upload error.