Deploy your first server

A script that deploys without anyone watching needs more than the six calls of the Quickstart: an SSH key stored in advance, a first-boot configuration, a wait for the deployment to finish, and a way to read the operation when it fails. In the samples, <api-key> stands for your API key, and a name in braces such as {serviceId} for an id an earlier step returned.

1. Store an SSH key

A key stored in the organization can be put on any server you deploy. Add SSH key takes a name and, as publicKey, the whole line of your .pub file (~/.ssh/id_ed25519.pub, for example). RSA, ED25519 and ECDSA keys are accepted.

curl --request POST \
  --url https://api.serverside.com/v1/organization/ssh-keys \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "laptop",
  "publicKey": "<public-key>"
}
'

Keep the id from the response. List SSH keys finds it again later.

2. Get the server

Pick a plan and a datacenter with stock, then order and pay for the server as in the Quickstart, which ends with its id. An organization with hourly billing creates the service in one call instead. Generate the idempotency key once (the output of uuidgen will do) and send the same value on a retry, so a request repeated after a network error is recognised as the same one:

curl --request POST \
  --url https://api.serverside.com/v1/services/baremetal \
  --header 'X-API-KEY: <api-key>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "offeringId": "<plan-id>",
  "datacenterId": "<datacenter-id>"
}
'

The new service's id is data.id in the response; the deploy, status and operation requests take it as {serviceId}.

A plan that sold out between listing and ordering is refused with 422 and the code OFFERING_NOT_AVAILABLE, by this call and by an order alike. If another order takes the last server in the moment after that check, the answer is 500 with UNHANDLED_EXCEPTION, so list the plans again before retrying a 500 here. A declined card never shows up at this stage. It appears in the result of Pay invoice, when the invoice is paid.

3. Deploy with a first-boot configuration

cloudInit takes a cloud-config document, run by the image's cloud-init on first boot. This one installs two packages and creates a user:

#cloud-config
packages:
  - htop
  - fail2ban
users:
  - name: deploy
    groups: sudo
    shell: /bin/bash

The deployment request carries it as a single JSON string, each line break written as \n:

curl --request POST \
  --url https://api.serverside.com/v1/services/baremetal/{serviceId}/operations/deploy \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "operatingSystemId": "<image-id>",
  "sshKeyIds": [
    "<ssh-key-id>"
  ],
  "raidVariant": "RAID1",
  "cloudInit": "#cloud-config\npackages:\n  - htop\n  - fail2ban\nusers:\n  - name: deploy\n    groups: sudo\n    shell: /bin/bash"
}
'

cloudInit is for Linux images. A Windows deployment accepts the field and never reads it, and a deployment that installs an application refuses it. On a Linux image without the cloud-init package the deployment fails in its last step, after the disk has been written.

4. Wait for it to finish

While an operation runs, the service's state is OPERATION_IN_PROGRESS. Send Get service status every 20 seconds or so until it is not:

curl --request GET \
  --url https://api.serverside.com/v1/services/baremetal/{serviceId}/status \
  --header 'X-API-KEY: <api-key>'

Between polls, data.operation.lastProgressMessage names the stage the deployment has reached. Once the state changes, data.lastOperation.state says how it ended: COMPLETED means the server is installed. Its address is primaryIpv4 on Get bare metal service. Log in as the username the deploy request named, or as the image's defaultUser when it named none. Windows images always create Administrator, with the request's password, and take no SSH keys.

5. When a deployment fails

A FAILED operation keeps its trail. Get operation with the operation's id returns failureCategory, the lastProgressMessage and updates: every progress report the deployment sent, each with its time, progress and message. The last entries show the stage it reached.

curl --request GET \
  --url https://api.serverside.com/v1/services/baremetal/{serviceId}/operations/{operationId} \
  --header 'X-API-KEY: <api-key>'

An installer failure reports failureCategory as unknown for now. The lastProgressMessage and the last updates are then what separate a disk or RAID step from an image download that did not finish.

A new deployment can start as soon as the service is ACTIVE again. If the second attempt fails at the same stage, contact support through the form in the cloud console or at tech@serverside.com. The form does not attach the service, so name the server in the message and include the operation's id, its failureCategory and its lastProgressMessage.