Hosting

Stacklane sells web hosting on cPanel/WHM and DirectAdmin, and game servers on Pterodactyl. You connect your panel servers and create hosting plans. When a customer orders a plan, Stacklane creates the account on the panel server. Only staff with the owner or admin role can manage servers and plans.

Panel servers#

Open Panel servers in the Hosting group and click Add server.

FieldRules and meaning
Typecpanel, directadmin or pterodactyl. You cannot change the type later.
NameRequired. Up to 60 characters.
Panel URLThe address of the panel. Must start with http:// or https://.
UsernameDepends on the type. See below. Up to 64 characters.
SecretThe API token, login key or API key. Required for a new server. Leave it empty to keep the current one. When you change the URL to another host, you must enter it again.
Maximum accountsOptional. 1 to 100,000. When the server has this many accounts, its plans are not available for new orders.
Statusactive or disabled. Plans on a disabled server are not available for new orders.
Verify the TLS certificate of the panelOn by default. Turn it off only for self-signed certificates on a network you trust.

The secret is stored encrypted. The server list shows how many accounts each server has.

After you save, click Test connection next to the server in the list. Stacklane connects to the panel and shows the result:

TypeThe test shows
cPanel/WHMThe WHM version.
DirectAdminThe number of accounts.
PterodactylThe number of locations.

cPanel/WHM#

FieldValue
Panel URLThe WHM address, for example https://server.example.net:2087.
UsernameThe WHM user. When you leave it empty, Stacklane uses root.
SecretA WHM API token.

Stacklane calls the WHM JSON API (/json-api/, API version 1) with the header Authorization: whm <user>:<token>. It uses the functions version, createacct, suspendacct, unsuspendacct, removeacct and create_user_session. Give the token permission for these functions.

DirectAdmin#

FieldValue
Panel URLFor example https://server.example.net:2222.
UsernameRequired. The admin or reseller user.
SecretA login key for that user.
Shared IP addressThe IP address for new accounts. You can also set it per plan. One of the two is required.

Stacklane uses CMD_API_SHOW_ALL_USERS, CMD_API_ACCOUNT_USER, CMD_API_SELECT_USERS and /api/login-url. The login key needs access to these commands.

Pterodactyl#

FieldValue
Panel URLFor example https://panel.example.net.
UsernameNot used.
SecretAn Application API key.
Location IDThe location for new servers. You can also set it per plan. One of the two is required.

Stacklane uses the Application API (/api/application). The key needs read and write access to users, servers, locations and nests.

FieldValue
Client API keyOptional. A Client API key (ptlc_) of a root administrator. With this key, customers manage their game servers inside Stacklane.

Game servers without a public panel#

When you set a Client API key, customers get a full game server screen in the portal and never see the Pterodactyl panel. Stacklane talks to the panel and to Wings for them:

FeatureHow it reaches the server
Console, live statistics and power actionsStacklane opens the Wings websocket itself and passes the frames to the browser.
File manager, editor, uploads and downloadsStacklane streams the files between the browser and Wings. Downloads use a single-use link that is valid for 60 seconds. Uploads can be up to 1 GiB.
Backups, databases, schedules, ports and startup variablesStacklane calls the Client API of the panel.
Minecraft versions, plugins, mods and modpacksStacklane downloads the files from PaperMC, Purpur, Fabric, Mojang or Modrinth and uploads them to the server.

Because of this, neither the panel nor the Wings nodes need to be reachable from the internet. Only Stacklane must reach them:

  1. Allow Stacklane to reach the panel URL and the Wings API port (8080 by default) of every node.
  2. Keep the game ports (for example 25565) open to players, as before.
  3. Keep the Wings SFTP port (2022 by default) open only if you want customers to use SFTP. The Settings tab shows the SFTP address and user name.
  4. Allow Stacklane to make outgoing HTTPS requests to fill.papermc.io, fill-data.papermc.io, api.purpurmc.org, meta.fabricmc.net, piston-meta.mojang.com, piston-data.mojang.com, api.modrinth.com and cdn.modrinth.com.

Stacklane sends the panel URL as the Origin of the websocket, so the default Wings configuration works without changes.

The Client API key acts for a root administrator. Stacklane only uses it for servers that belong to the customer who makes the request, and every change is written to the audit log.

Minecraft extras#

For servers whose egg has the eula feature, the portal shows a Minecraft tab:

Hosting plans#

Open Hosting plans in the Hosting group and click Add plan. Add a panel server first.

FieldRules and meaning
ServerThe panel server for new accounts on this plan. You can move a plan to another server of the same type.
NameRequired. Up to 60 characters. Customers see it.
SlugRequired. Lowercase letters, digits and hyphens, up to 40 characters. Must be unique.
Monthly price0 to 1,000,000.00, without VAT, in the billing currency.
Statusactive or disabled. Customers can only order active plans.
DescriptionUp to 500 characters.
FeaturesUp to 2,000 characters. One feature per line. The order page shows each line as a feature.
Sort orderA number that sets the order in lists.

Below these fields you set the panel options of the plan. The options depend on the type of the server.

Options for cPanel/WHM and DirectAdmin#

OptionRequiredMeaning
packageYesThe name of the package, exactly as it exists on the panel server.
ipDirectAdmin only, when the server has no shared IPThe IP address for new accounts. Overrides the server setting. Only available through the API.

Options for Pterodactyl#

OptionRequiredDefaultMeaning
nest_idYesThe nest of the egg.
egg_idYesThe egg to install.
memory_mbYesMemory limit in MiB.
disk_mbYesDisk limit in MiB.
cpu_percentNo100CPU limit in percent.
databasesNo1Maximum number of databases.
backupsNo2Maximum number of backups.
location_idWhen the server has no location IDOverrides the server setting.
swap_mbNo0Swap in MiB.
ioNo500Block IO weight.
allocationsNo1Maximum number of allocations.
docker_imageNoThe egg's imageDocker image for the server.
environmentNoAn object with values for egg variables. Overrides the egg defaults.

The form in the portal has fields for the first seven options. Set the others through the API, in the options object of the plan.

Stacklane reads the startup command and the variables of the egg from Pterodactyl. Each variable gets its default value, unless environment sets another value.

Provisioning#

When a customer orders a plan:

  1. Stacklane checks that the plan is active, the server is active and the server has room for another account.
  2. It creates the service with the status provisioning. It makes a username from the first letters of the domain or the service name and a few characters of the service ID, for example shopea1b. It also makes a random password and stores it encrypted.
  3. It adds a service.create task and answers with 202 Accepted.
  4. A background worker creates the account on the panel:
    • cPanel/WHM: a new account with the domain, the package, the username, the password and the contact email;
    • DirectAdmin: a new user with the domain, the package, the IP address and the password;
    • Pterodactyl: a panel user for the organization (if it does not exist yet), then a new server with the limits of the plan. The server starts when the installation is done.
  5. On success the service becomes active. On failure it becomes error.

The contact email is the billing email of the organization. If the organization has none, it is the email of the user who placed the order.

cPanel and DirectAdmin plans need a domain. The customer enters it when ordering. Pterodactyl plans do not need a domain.

Customer access#

On the service page the customer can:

A customer cannot cancel a suspended service. They have to contact support.

When provisioning fails#

Stacklane does not retry failed tasks. The error is in the service log, in a line task failed, and in the task list of the organization (GET /api/cloud/v1/tasks). Common errors:

ErrorWhat to do
control panel is unreachable: ...Check the URL, the network and the TLS setting. Use Test connection.
control panel rejected the request: ...Read the reason from the panel. Often the package does not exist, the username is taken or the key misses a permission.
plan is misconfigured: missing packageSet the package option of the plan.
plan is misconfigured: missing ipSet the shared IP address on the DirectAdmin server, or ip on the plan.
plan is misconfigured: missing location_idSet the location ID on the Pterodactyl server or the plan.
plan is misconfigured: a domain is requiredThe plan type needs a domain.

After you fix the cause, the customer can cancel the failed service and order again.

Suspension#

A service can be suspended in two ways.

On cPanel/WHM, Stacklane suspends with the reason "Suspended by billing". On DirectAdmin and Pterodactyl it uses the normal suspend function of the panel.

Suspended services are still billed. Terminated services are not.

Manage services through the API#

There is no page for these actions in the portal. Use a staff access token. See API.

curl https://panel.example.com/api/admin/hosting/services \
  -H "Authorization: Bearer $ACCESS_TOKEN"

curl -X POST https://panel.example.com/api/admin/hosting/services/<service-id>/suspend \
  -H "Authorization: Bearer $ACCESS_TOKEN"
ActionAllowed when
suspendThe service is active.
unsuspendThe service is suspended.
terminateThe service is not already terminating.

The action fails with 409 and the code busy when it is not possible in the current state, or when another task for the service is still running. Each action answers with 202 Accepted and the task.

API endpoints#

MethodPathStaff rolesDescription
GET, POST/api/admin/hosting/serversowner, adminList or add panel servers.
PUT/api/admin/hosting/servers/{id}owner, adminUpdate a panel server.
POST/api/admin/hosting/servers/{id}/checkowner, adminTest the connection.
GET, POST/api/admin/hosting/plansowner, adminList or add plans.
PUT/api/admin/hosting/plans/{id}owner, adminUpdate a plan.
GET/api/admin/hosting/servicesowner, admin, supportList the services of all organizations.
POST/api/admin/hosting/services/{id}/{action}owner, admin, supportsuspend, unsuspend or terminate.

Example plan for Pterodactyl:

{
  "server_id": 3,
  "slug": "minecraft-4gb",
  "name": "Minecraft 4 GB",
  "description": "Java edition server",
  "features": "4 GB memory\n20 GB disk\nDaily backups",
  "monthly_price_cents": 1200,
  "currency": "EUR",
  "options": {
    "nest_id": 1,
    "egg_id": 3,
    "memory_mb": 4096,
    "disk_mb": 20480,
    "cpu_percent": 200,
    "backups": 3,
    "environment": { "SERVER_JARFILE": "server.jar" }
  },
  "status": "active",
  "sort": 10
}