# Creating a virtual machine

This guide walks you through creating your first virtual machine (instance) in the OpenStack dashboard
([Horizon](https://datalab.tuwien.ac.at/infrastructure/openstack/login/)). If you have not yet set up access, see [logging in](https://datalab.tuwien.ac.at/infrastructure/openstack/login/) and
[creating a project](https://datalab.tuwien.ac.at/infrastructure/openstack/creating-a-project/) first.

## Step 1: Add an SSH key pair

You need an SSH key pair to log in to your VM. If you already have one you want to use, skip to "import an existing
key". Otherwise, generate a new one:

``` bash
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519
```

This creates a public key (`~/.ssh/id_ed25519.pub`) and a private key (`~/.ssh/id_ed25519`). Keep the private key
secure and never share it.

Now, in Horizon:

1. Go to **Project → Compute → Key Pairs** and click **Create Key Pair**.
2. Either **create a new key pair** (Horizon will download the private key for you) or
   **import your public key**:

   ``` bash
   cat ~/.ssh/id_ed25519.pub
   ```

   Paste the output into the **Public Key** field.

!!! danger
    If you create a key pair through Horizon and lose the downloaded private key before first use, you will not be
    able to log in to the instance. Keep a copy somewhere safe.

## Step 2: Open the relevant ports

By default, the `default` security group allows **no inbound traffic**. To reach your instance from outside, you must
add rules for the ports you need (for example SSH) to the default group, or attach an additional security group.
See [networking](https://datalab.tuwien.ac.at/infrastructure/openstack/networking/#security-groups).

## Step 3: Boot an instance

1. Go to **Project → Compute → Instances** and click **Launch Instance**.
2. Give the instance a **Name**.
3. **Source**: select an [image](https://datalab.tuwien.ac.at/infrastructure/openstack/images/). (Optional: choose a larger **Create New Volume** here if the image's
   default disk is too small.)
4. **Flavor**: select a [flavor](https://datalab.tuwien.ac.at/infrastructure/openstack/flavors/). Use the arrow to reveal the size options.
5. **Networks**: select the network to attach. The `default`/`private` network is usually selected automatically.
6. **Security Groups**: the default group is selected. Add any additional ones you prepared in Step 2.
7. **Key Pair**: select the key pair from Step 1. **This is required** — without it you cannot log in.
8. Click **Launch Instance**.

After a few minutes the instance appears in **Instances** with a running state.

## Step 4: Assign a floating IP

An instance created in a private network has no public address by default. To reach it from outside, allocate and
attach a floating IP:

1. Go to **Project → Network → Floating IPs** and click **Allocate IP to Project**.
2. Select the public network (e.g. `public`) and click **Allocate IP**.
3. Next to the new IP, click **Associate** and choose your instance.

!!! note
    Floating IPs are a finite resource. Each becomes a DNS record (see [networking](https://datalab.tuwien.ac.at/infrastructure/openstack/networking/#dns)) and you should
    release them when you no longer need them.

## Step 5: Log in

The login user depends on the [image](https://datalab.tuwien.ac.at/infrastructure/openstack/images/) you chose, for example `ubuntu` for Ubuntu, `cloud-user`/`rocky` for
Rocky, or `admin` for Debian-compatible images:

``` bash
ssh ubuntu@<floating ip>
```

The first login uses the key pair from Step 1, so no password is required.

## Next steps

- [Mount a volume or add persistent storage](https://datalab.tuwien.ac.at/infrastructure/openstack/storage/).
- [Create a private network or router](https://datalab.tuwien.ac.at/infrastructure/openstack/networking/).
- [Interact with your VM from the command line](https://datalab.tuwien.ac.at/infrastructure/openstack/cli/).