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.
| Field | Rules and meaning |
|---|---|
| Type | cpanel, directadmin or pterodactyl. You cannot change the type later. |
| Name | Required. Up to 60 characters. |
| Panel URL | The address of the panel. Must start with http:// or https://. |
| Username | Depends on the type. See below. Up to 64 characters. |
| Secret | The 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 accounts | Optional. 1 to 100,000. When the server has this many accounts, its plans are not available for new orders. |
| Status | active or disabled. Plans on a disabled server are not available for new orders. |
| Verify the TLS certificate of the panel | On 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:
| Type | The test shows |
|---|---|
| cPanel/WHM | The WHM version. |
| DirectAdmin | The number of accounts. |
| Pterodactyl | The number of locations. |
cPanel/WHM#
| Field | Value |
|---|---|
| Panel URL | The WHM address, for example https://server.example.net:2087. |
| Username | The WHM user. When you leave it empty, Stacklane uses root. |
| Secret | A 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#
| Field | Value |
|---|---|
| Panel URL | For example https://server.example.net:2222. |
| Username | Required. The admin or reseller user. |
| Secret | A login key for that user. |
| Shared IP address | The 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#
| Field | Value |
|---|---|
| Panel URL | For example https://panel.example.net. |
| Username | Not used. |
| Secret | An Application API key. |
| Location ID | The 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.
| Field | Value |
|---|---|
| Client API key | Optional. 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:
| Feature | How it reaches the server |
|---|---|
| Console, live statistics and power actions | Stacklane opens the Wings websocket itself and passes the frames to the browser. |
| File manager, editor, uploads and downloads | Stacklane 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 variables | Stacklane calls the Client API of the panel. |
| Minecraft versions, plugins, mods and modpacks | Stacklane 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:
- Allow Stacklane to reach the panel URL and the Wings API port (8080 by default) of every node.
- Keep the game ports (for example 25565) open to players, as before.
- 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.
- 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.comandcdn.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:
- Server type and version: Paper, Purpur, Fabric or Vanilla, in any released version. Stacklane replaces the server jar named in the
SERVER_JARFILEvariable and keeps the worlds. - Plugins, mods and data packs: a search on Modrinth that only shows projects for the server type and version. Installing places the file in
/plugins,/modsor/world/datapacks. - Modpacks: Fabric modpacks from Modrinth. Stacklane installs the mods for the server side, applies the pack's settings and installs the matching Fabric server. With Start fresh, the current mods and config are removed and the current worlds are renamed to
world-before-modpack-<date>. - Server address: a free subdomain under your own zone, see Free subdomains for game servers.
- EULA: when the console shows that the Minecraft EULA is not accepted, the customer can accept it and start the server with one click.
Hosting plans#
Open Hosting plans in the Hosting group and click Add plan. Add a panel server first.
| Field | Rules and meaning |
|---|---|
| Server | The panel server for new accounts on this plan. You can move a plan to another server of the same type. |
| Name | Required. Up to 60 characters. Customers see it. |
| Slug | Required. Lowercase letters, digits and hyphens, up to 40 characters. Must be unique. |
| Monthly price | 0 to 1,000,000.00, without VAT, in the billing currency. |
| Status | active or disabled. Customers can only order active plans. |
| Description | Up to 500 characters. |
| Features | Up to 2,000 characters. One feature per line. The order page shows each line as a feature. |
| Sort order | A 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#
| Option | Required | Meaning |
|---|---|---|
package | Yes | The name of the package, exactly as it exists on the panel server. |
ip | DirectAdmin only, when the server has no shared IP | The IP address for new accounts. Overrides the server setting. Only available through the API. |
Options for Pterodactyl#
| Option | Required | Default | Meaning |
|---|---|---|---|
nest_id | Yes | The nest of the egg. | |
egg_id | Yes | The egg to install. | |
memory_mb | Yes | Memory limit in MiB. | |
disk_mb | Yes | Disk limit in MiB. | |
cpu_percent | No | 100 | CPU limit in percent. |
databases | No | 1 | Maximum number of databases. |
backups | No | 2 | Maximum number of backups. |
location_id | When the server has no location ID | Overrides the server setting. | |
swap_mb | No | 0 | Swap in MiB. |
io | No | 500 | Block IO weight. |
allocations | No | 1 | Maximum number of allocations. |
docker_image | No | The egg's image | Docker image for the server. |
environment | No | An 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:
- Stacklane checks that the plan is active, the server is active and the server has room for another account.
- 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 exampleshopea1b. It also makes a random password and stores it encrypted. - It adds a
service.createtask and answers with202 Accepted. - 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.
- On success the service becomes
active. On failure it becomeserror.
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:
- see the username and, after clicking Show password, the password;
- open the control panel with one click:
- cPanel: Stacklane creates a cPanel session and opens it;
- DirectAdmin: Stacklane asks DirectAdmin for a login URL;
- Pterodactyl: without a Client API key, Stacklane opens the page of the server in the panel. With a Client API key, the customer manages the server in the portal instead, see Game servers without a public panel;
- cancel the service. This deletes the account and all its data on the panel.
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:
| Error | What 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 package | Set the package option of the plan. |
plan is misconfigured: missing ip | Set the shared IP address on the DirectAdmin server, or ip on the plan. |
plan is misconfigured: missing location_id | Set the location ID on the Pterodactyl server or the plan. |
plan is misconfigured: a domain is required | The 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.
- By billing. When an invoice is overdue for longer than the Suspend after setting, Stacklane suspends all active services of the organization. When the organization has no overdue invoices anymore, Stacklane unsuspends the services that it suspended for billing. See Billing.
- By staff. Staff with the
owner,adminorsupportrole can suspend, unsuspend and terminate a service through the API.
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"
| Action | Allowed when |
|---|---|
suspend | The service is active. |
unsuspend | The service is suspended. |
terminate | The 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#
| Method | Path | Staff roles | Description |
|---|---|---|---|
GET, POST | /api/admin/hosting/servers | owner, admin | List or add panel servers. |
PUT | /api/admin/hosting/servers/{id} | owner, admin | Update a panel server. |
POST | /api/admin/hosting/servers/{id}/check | owner, admin | Test the connection. |
GET, POST | /api/admin/hosting/plans | owner, admin | List or add plans. |
PUT | /api/admin/hosting/plans/{id} | owner, admin | Update a plan. |
GET | /api/admin/hosting/services | owner, admin, support | List the services of all organizations. |
POST | /api/admin/hosting/services/{id}/{action} | owner, admin, support | suspend, 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
}