# Create an instance

> Order a Cloud Compute instance on its order page, with a plan, an operating system, a location, your SSH keys and any add-ons.

Source: https://docs.coritan.com/cloud-compute/create-an-instance/

In the dashboard:

- /dashboard/order/cloud-compute: https://www.coritan.com/dashboard/order/cloud-compute

The **Cloud Compute** order page asks five things, in numbered sections: **Plan**, **Operating system**, **Location**, **Settings** and **Add-ons**. The first four start with an answer chosen for you, and the summary beside them keeps the price up to date as you change them. Add-ons are other products bought in the same order, such as more floating IPs. We start building the instance once the first invoice is paid, and it boots with the image, hostname and SSH keys you chose.

## Before you begin

- [Create a Coritan account](/get-started/create-an-account/) and sign in.
- Credit on your account pays the first invoice when you place the order. Without enough credit, you pay the rest by card or PayPal on the page the order opens. To pay in one go, [add credit](/billing/add-credit/) first.
- Hourly billing needs a minimum total of deposits on your account before you can choose it. [How hourly billing works](/billing/hourly-billing/) explains the rule.
- To sign in over SSH without a password, have your SSH public key to hand, such as the contents of `~/.ssh/id_ed25519.pub`. [Connect to an instance over SSH](/cloud-compute/connect-to-an-instance/) shows how to make one.

## Choose a plan

1. In the [dashboard](https://www.coritan.com/dashboard/compute), go to **Cloud Compute** and select **Order instance**. You can also select the **Cloud Compute** card on the **Order a service** page. Either way, the order page opens at `https://www.coritan.com/dashboard/order/cloud-compute`.
2. At the top of **Plan**, choose how often to pay. The switch lists the billing cycles the plan sells, and a longer term names what it saves against paying monthly.
3. Choose a **Hardware tier**, if the page offers more than one. The tier sets the CPU class and the storage, and each tier sells the same sizes.
4. Under **Size**, choose a plan. Each row shows its price for the cycle, its vCPUs, memory, disk and monthly traffic. We start with the recommended plan, or else the smallest one on sale. A plan marked **Sold out** cannot be ordered anywhere right now.

When you choose hourly billing, a note under the sizes explains that hourly services draw on your credit as they run. If your account has not deposited enough yet, the note names the deposit it still needs, and **Top up credit** takes you to Billing to add it.

## Choose the operating system and the location

1. Under **Operating system**, choose a card under **Distribution**. We choose its newest release that the plan can run, and a card under the distributions lists every release to choose from.
   - The line under the releases names the user you sign in as and the disk the image needs.
   - A release the plan is too small for is greyed out, with the reason under it, such as `Needs at least 20 GB of disk`.
   - A distribution marked **Plan too small** has no release that fits the plan. Choose a larger plan, or another distribution.
2. Under **Location**, choose a data centre on the map or in the list under **Data centres**, which groups them by region. We start with the one marked **Closest to you**. Pick the one closest to the people who will use the instance: its address is local to that location. A location marked **Sold out** has no room for this plan right now.

You can rebuild the instance onto another image later, from its **Access** tab.

## Check the settings

1. Under **Settings**, keep the suggested **Hostname**, such as `ubuntu-fra-1`, or type your own, such as `web-1`. It takes letters, digits, hyphens and dots, up to 100 characters, with each part between dots at most 63 characters. The field turns capitals into lower case and drops any other character as you type. The instance uses it as its hostname.

   The **Access** tab accepts a hostname without dots only. If you order a name with dots, such as `web-1.example.com`, you can later replace it only with a single label, such as `web-1`.
2. Under **SSH keys**, paste one OpenSSH public key per line. Cloud-init adds them to the image's default user on the first boot. This is optional.
3. Leave the switch on the **Public IPv4 address** card on to order the included address. It costs nothing while it stays attached as the instance's primary address. We take it from the instance's location and attach it when setup finishes.
4. If the plan has **Plan options**, answer them. We add the price of any option you take to every charge.

> [!IMPORTANT]
> If you turn off the **Public IPv4 address** switch, the instance has no public address. You can reach it only through the [display console](/cloud-compute/console/) until you [attach a floating IP](/floating-ips/attach-and-detach/) to it. You also cannot add floating IPs or a DDoS Shield profile to the order.

## Add products to the order

Under **Add-ons**, turn on the switch of anything you want to buy with the instance. This is optional. Each card shows its price for the order's billing cycle, and everything you add goes on the instance's first invoice:

- **Floating IPs** are more public IPv4 addresses. Set **How many** you want, up to four in one order, and choose a size under **Size** when more than one is on sale. They come from the address pool in the instance's location, and we attach them to the instance when it is ready.
- A **DDoS Shield profile** gives the instance's addresses your own protection mode, firewall rules and packet rate limits. It protects the included address and any floating IPs in the order. Give it a **Profile name**, or we name it after the hostname. Without one, the addresses keep the scrubbing every address on the platform gets.
- **Mail Hosting** adds mailboxes on your own domain. Choose a plan if there is more than one, and add a **Domain** now or later.
- **SMTP Relay** delivers the mail your applications send. Choose a plan if there is more than one, and add a **Sending domain** now or later.

A card that cannot be added says why, and its switch stays off. Floating IPs and a DDoS Shield profile both need the included public IPv4, and floating IPs also need a location whose pool has addresses left. Each add-on becomes a service of its own, which you can cancel on its own later. [Add products to the order](/get-started/order-a-service/#add-products-to-the-order) has the rules for every product.

## Place the order

1. Check the summary under **Your order**. On a phone it follows the sections, and **Review order** at the bottom of the screen takes you there. It lists the plan, the operating system, the location and the hostname, each with **Change** beside it to go back to its section. Under **Billed** it lists the plan, the public IPv4 address as **Included**, and each add-on with its price.
2. Check the **Total**. It shows the price for each billing cycle, any one-time setup fee, what a longer term saves and what is due today. The line under it says how the first invoice will be paid.
3. If the button is greyed out, read the line under it. It names the first answer still missing, such as `Choose an operating system.`, and selecting it takes you to that section.
4. Select the button. It reads **Deploy instance** when your credit pays the first invoice or your account is billed in arrears, and **Place order and pay** when you pay on the next page.

If we refuse the order, **Could not place the order** appears above the button with the reason, and your choices stay as they were. Otherwise the order's own page opens. When its title reads **Order placed, payment due**, pay under **Pay invoice**, as [Pay and follow the order](/get-started/order-a-service/#pay-and-follow-the-order) describes. If you leave without paying, pay the invoice under [Invoices](/billing/invoices/). Setup starts once it is paid.

## Result

The order's page shows **Setting up** while we build the instance, and checks on it every few seconds. Its title becomes **Your order is ready** when the instance and every add-on are active. The instance appears on the [Services](/get-started/services/) page as soon as you order it, and on the **Cloud Compute** page once it has been built and started, with the included address attached. We email you when each service is ready.

We generate a password for the default user when we build the instance, but no page shows it. The **Access** tab shows only whether one is set, although the order pages say you will find the password there. Sign in with the SSH key you added, or [reset the password](/cloud-compute/access/#reset-the-password) to get one you can use.

## Troubleshooting

The button under the summary is greyed out
: The line under it names the first answer still missing. Select it to go to that section.

`This plan has no active price.`
: The plan has no price on sale on any billing cycle. Choose another plan.

`This plan is sold out everywhere right now.`
: No location has room for this plan. Choose another size or hardware tier.

`Hourly billing needs a deposit first.`
: The note under **Size** names the deposit your account still needs. Select **Top up credit** to add it, or choose another cycle.

`That image cannot go on this plan: needs at least 20 GB of disk.`
: You chose a smaller plan after the image. Choose a larger plan, or another release.

**Could not load the images**
: The list of images did not load. Select **Try again**.

**No images are ready right now**
: We are still preparing the images for the plan. Try again shortly.

`That location has no capacity for this plan.`
: The location filled up after you chose it. Choose another. **Every location is sold out for this plan** means you need a different size or tier.

`Use letters, digits and hyphens; each part at most 63 characters.`
: A part of the hostname is longer than 63 characters, or starts or ends with a hyphen. `A hostname cannot start or end with a dot or hyphen.` and `A hostname cannot contain consecutive dots.` name the other rules.

`Each line must be one OpenSSH public key, e.g. "ssh-ed25519 AAAA… you@laptop".`
: A line in **SSH keys** is not a public key. Paste the `.pub` file, one key per line. The page accepts `ssh-ed25519`, `ssh-rsa`, `ssh-dss`, `ecdsa-sha2-nistp256`, `ecdsa-sha2-nistp384`, `ecdsa-sha2-nistp521`, `sk-ssh-ed25519@openssh.com` and `sk-ecdsa-sha2-nistp256@openssh.com` keys.

The **Floating IPs** card says `Keep the included public IPv4 to add floating IPs.`
: Turn the switch on the **Public IPv4 address** card back on. The included address is free, and floating IPs are extra addresses on top of it.

The **Floating IPs** card says the pool is sold out
: The location has no addresses left to sell. Choose another location, or order the instance without them and [order a floating IP](/floating-ips/order-a-floating-ip/) later.

**No address**
: We built the instance but could not attach the address ordered with it. The address is still on your account: go to **Floating IPs**, open it, and attach it to the instance as [Attach and detach a floating IP](/floating-ips/attach-and-detach/) describes.

## Related

- [Operating system images](/cloud-compute/images/) lists what the images have in common and how they differ.
- [Connect to an instance over SSH](/cloud-compute/connect-to-an-instance/) is the next step once the instance runs.
- [Order a service](/get-started/order-a-service/) explains ordering and payment for every product.
- [Data centres and locations](/platform/data-centres/) describes each location.

## With the API

Three requests give you the values an order needs:

- `GET /api/v1/products/` lists the plans. A Cloud Compute plan has `module_name` set to `vps`. Its `pricing` list holds one row per billing cycle, each with the `id` you send as `pricing_id`, and its `locations` list gives each location's `code` and whether it is `orderable` for the plan.
- `GET /api/v1/client/vps/templates` lists the images you can order, each with the `id` you send as `template_id`. [Operating system images](/cloud-compute/images/#with-the-api) describes the fields.
- `GET /api/v1/locations` lists every active location with its `code`.

```bash
curl "https://api.coritan.com/api/v1/products/?per_page=200" \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

Place the order with `POST /api/v1/services/order`, as [Order a service](/get-started/order-a-service/#with-the-api) describes, with the plan's `product_id` and the cycle's `pricing_id`. Send the instance's settings in `config`:

`location`
: The location code, such as `fra`.

`template_id`
: The image's `id`.

`hostname`
: The instance's hostname. When you leave it out of `config`, we use the top-level `hostname`.

`ssh_keys`
: Optional. OpenSSH public keys, one per line.

`order_ipv4`
: Optional, `false` when left out. Send `true` to order the included public IPv4 address with the instance, as the dashboard does.

`pool_id`
: Optional. The IP pool to take the included address from. Without it we use a pool in the instance's location. [IP pools and regions](/floating-ips/pools/) lists them.

`allow_pool_fallback`
: Optional, `false` when left out. Send `true` to accept an address from a pool in another region when the instance's location has none, or when the `pool_id` you sent is in another region.

`prefix_len`
: Optional, `32` when left out. `32` orders one address. `24` to `29` order a subnet instead, which is billed at its catalogue price and is accepted only where subnets are on sale. [How subnets work](/floating-ips/subnets/) explains them.

The plan sets the instance's size, so leave `cpu_cores`, `memory_mb` and `disk_gb` out.

To buy add-ons in the same order, list them in `addons`, as [Add-ons in the order](/get-started/order-a-service/#add-ons-in-the-order) describes. An instance takes up to 4 floating IPs, and only with `"order_ipv4": true`. A DDoS Shield profile protects the included address and the floating IPs in the order. This example adds one floating IP:

```bash
curl -X POST https://api.coritan.com/api/v1/services/order \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": 12,
    "pricing_id": 34,
    "hostname": "web-1",
    "config": {
      "location": "fra",
      "template_id": 7,
      "hostname": "web-1",
      "order_ipv4": true,
      "ssh_keys": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExample alex@example.com"
    },
    "addons": [
      {"product_id": 31, "quantity": 1}
    ]
  }'
```

The response answers `201` with the new `service`, a service for each add-on in `addons`, `invoice_id`, `requires_payment`, `amount_due` and a `message`. When `requires_payment` is `true`, pay the invoice it names before setup starts. Once the instance exists, `GET /api/v1/client/vps` lists it with its `uuid`.

A second identical order (same plan, cycle and hostname) within two minutes of the first, while the first is still pending, returns the first order with the message `Order already submitted` instead of a new one.

Errors in the order answer `422` with a list under `detail.errors`:

- `template_id is required`, or `location is required (airport code, e.g. iad)`.
- `OS template 7 is not ready in location 'fra'`: that image cannot be built in that location. Choose another image or location.
- `No available ... with sufficient capacity for this Cloud Compute instance`: the location has no room for the plan.
- `No sellable IPv4 pool available in location 'fra'`: we have no addresses to sell in that location. Send `allow_pool_fallback`, order without `order_ipv4`, or add a floating IP later.
- `IP pool region 'iad' does not match compute location 'fra' (set allow_pool_fallback to override)`: the `pool_id` you sent is in another region.
- `Keep the included public IPv4 to add floating IPs. It is free, and floating IPs are extra addresses on top of it.`: the order has floating IPs in `addons` without `"order_ipv4": true`.
- `An instance takes at most 4 floating IPs in one order.`: the `quantity` of floating IPs is more than 4.

An hourly cycle before your account holds the deposit answers `403` with `You must deposit at least $10 before using hourly billing services`.

## API

- `POST /api/v1/services/order`: Order a platform service, and any add-ons bought with it (https://docs.coritan.com/api/reference/client/services/#op-post-api-v1-services-order)