Quick Start

This guide shows how to provision a virtual machine instance on Oxide from a cloud image in just a few minutes. We will use the web console, but you can achieve the same outcome with our CLI or Terraform provider just as easily.

Creating a project

The first thing you’ll see after logging in is the Projects page. A project is a collection of resources like instances, disks, images, VPCs, and floating IPs. Instances must be created within a project. Create one by clicking New project.

Give your project a name and click Create project in the lower right corner. You’ll be taken into your project and shown the Instances page. There won’t be any instances yet.

Modal form titled "Create Project"

Creating an instance

Click New instance to go to the instance create form.

Instance list screen with an empty state. CTA buttons that prompt user to create an instance.

There are a lot of options on this page, but we’re going to keep it simple. Give the instance whatever name you’d like and scroll down.

Hardware

Under Hardware you have the option to set up a pre-configured choice — a high CPU instance, a high memory instance, or a general purpose instance — or to set your own CPU and memory values. Leave it on the default of 2 vCPUs and 8 GiB RAM.

Instance create form including large radio buttons with hardware configurations

Boot disk

When you get to Boot disk you’ll see two options.

  1. Silo Images: images available for use in all projects in the silo

  2. Project Images: images that you upload for use with your project

Instance create form with inputs to select a boot disk image
Note
The Oxide rack does not come with any preloaded images, but many Linux distributions provide native cloud images that can be deployed in the Oxide rack. If no image has been made available yet in the silo, you can follow the steps in How to make test images to import a project image for yourself.

For the instance creation steps below, we’re going to use Debian-12-generic, one of the examples in How to make test images. If you have a different image, the steps are the same.

Authentication

Further down the page, you’ll see the Authentication section, which lists all the SSH keys in your profile.

It’s likely that you don’t have any SSH keys yet. You can add one right here by clicking Add SSH key.

If you don’t have a SSH key pair for use on Oxide yet, you can follow these quick instructions to generate a new one.

Once the key has been added, you will be able to select it as an authorized key on the instance for SSH access. You will also have the key in your profile for future use.

Submit

You can leave everything else on the form alone. Click Create instance at the bottom of the page.

Using your instance

After you create your new instance, you’re taken directly to the instance detail page, where you’ll see a few tabs: storage, metrics, network interfaces, connect.

Instance view page showing various instance attributes and tabs

Serial console

Clicking on Connect will let you access the instance’s serial console directly from the web UI. You’ll be doing this via SSH next.

Tab that prompts user to connect to instances serial console
Loading state as the user connects to the instance serial console

External IP address

In order to SSH into the instance next, you’ll need its external IP address, which is available at the top of the instance page. Copy the External IP value.

Access through SSH

First you’ll need a command line interface that interacts with the instance. How you do this will depend on your operating system.

If you have a Windows 10 or 11 workstation:

  1. Click on the Start button on your Windows screen.

  2. Search for Command Prompt, and click on it. That will open the default Terminal window.

On macOS, open a Terminal window by going to Applications > Utilities > Terminal.

At the Command Prompt enter (without any curly brackets):

ssh -i {private key location} debian@{external IP}

If your SSH key has the default name and location (i.e. $HOME/.ssh/id_rsa), you can exclude the -i argument. You might get an SSH known hosts warning; go ahead and connect to the server.

You’ll then see a prompt, from which you can do any of the normal things you’d do when SSH-ing into a server.

External connectivity

All instances are set up with outbound external connectivity by default. You can start using your new VM to install or update the OS packages after logging in.

Feel free to do whatever you like with your new VM. If you are new to Debian, you can follow Install a test Debian package to try running a simple utility program.

If you are running an application that takes inbound traffic, you’ll want to modify the default firewall settings such that the application is accessible from external hosts. The firewall change involves just a few additional steps, as illustrated in the web server example in the appendix.

Note
The default firewall settings allow SSH and ICMP access to your VMs from any external host (e.g., your workstation). VMs running in the same private network (VPC) are also permitted to access each other on any port and network protocol by default.

Deleting the instance

In order to delete an instance, you first have to stop it.

Stopping the instance

On the Instances page, click the three dots (more actions button) on the right side of your instance’s row. You’ll notice that the Delete option is not available yet. Click Stop.

The instance status will change to Stopping. Click the refresh button to get the current status.

Deleting the instance

Once the instance is stopped, click the three dots (more actions button) to the right of the instance again. The option to delete is now available. Click Delete.

Table of instances with dropdown

A box will appear asking for confirmation. Click Confirm to delete the instance.

The disks attached to the deleted instance are put into the detached state. They can be attached to another instance or re-used to create a new instance. If the disks are no longer needed, you may also delete them.

The external IP addresses allocated to the deleted instance are now freed up and can be assigned to other new instances.

Appendix

How to make test images

Linux OS

For testing purposes, you can download one of the published generic cloud image from Debian, for example,

Windows OS

The creation of Windows images is a bit more involved but we provide a tool and a set of comprehensive instructions to make it easier. Please see the Windows Instances guide.

How to import an image file

In the web console, navigate to your project. Click on Images on the left side bar.

Now click on Upload image on the right side of the page.

This will open the Upload image box. Give your image a name and fill in the rest of the required information. For this example, we’ll use the Debian image mentioned above. Once you have downloaded the image to your workstation, click on Upload image in the lower right of the box.

Modal form with inputs to upload and create an image

When the image has uploaded successfully click Done in the lower right of the box.

You should now see the newly uploaded image listed on the Images page. The image will be available for creating the boot disk of a new instance.

More information about how to manage images can be found in the Images guide.

How to create an SSH key

This is a brief guide on how to create an SSH key with Windows 11, Linux, and Mac OS. The particular commands needed might be different than what is below, depending on your particular version of each OS and your choice of SSH key options.

Mac and Linux

To generate an SSH key pair on Mac OS, first open a Terminal window to get the command line interface.

On your workstation, run the command:

ssh-keygen

Next you will be prompted to provide the location where you want to create the public and private key pair. Leave this empty to create the key in the default location, which is $HOME/.ssh/id_rsa.

You may be prompted to choose a passphrase. There is none needed if you do not want to use one.

elijah@oxide ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key (/Users/elijah/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /Users/elijah/.ssh/id_rsa
Your public key has been saved in /Users/elijah/.ssh/id_rsa.pub
The key fingerprint is:
SHA256:0oRCexM0Yddq3isfw9mZrsg1suJf6AT2 elijah@oxide.computer
The key's randomart image is:
+---[RSA 3072]----+
|    ..*...       |
|   . o =  .      |
|    o + ..       |
|     o +o        |
|      =oS..      |
|     o *.B.+ +   |
|      o * #.= .  |
|      .=.X.B .   |
|     .EoBo+.o    |
+----[SHA256]-----+

Windows 11

In Windows 11 you can generate SSH keys directly from the Command Prompt without needing any third party solutions. (These instructions should also be applicable to Windows 10)

  1. Click on the Start button on your Windows screen.

  2. Search for Command Prompt, right-click the top result, and select the `Run as Administrator" option.

  3. Type the following command to generate a pair of SSH keys and press Enter:

ssh-keygen
  1. (Optional) Confirm a descriptive name for the file and press Enter.

  2. (Optional) Confirm a passphrase for the SSH keys. (Note: The passphrase is an optional layer of security to protect the keys. If you don’t enter a password when authenticating, you won’t be asked to confirm the passphrase.)

  3. Confirm the passphrase one more time and press enter.

Once you complete the steps above, the private and public keypair will be generated and stored in the .ssh folder inside your profile folder. The private key will not include a file extension, while the public key will have a .pub extension.

How to manage SSH keys

The SSH keys you added on the Create Instance page can be found in your account settings. To navigate there, click on your user name in the upper right of the screen and choose Settings.

This will open your Profile page. Click on SSH Keys on the left side bar.

To add another public key, click on the Add SSH Key button on the right of the page.

This will open the Add SSH Key form. Enter a name for your public key, then click Add SSH Key in the bottom right of the box.

Modal form titled "Add SSH key" with inputs to add a SSH public key

To remove an existing key, simply click on the three dots on the right-most column of the SSH key table and click Delete.

Note
SSH key changes in your profile affect only the keys listed for selection when you create new instances. They do not affect the authorized keys in instances that you have already provisioned.
How to install a test Debian package

Assuming that you have executed sudo apt update earlier, you can now type and execute this command

sudo apt install ncal

in the SSH session, which will install the ncal package.

Once you’ve done that, if you enter cal or cal 2024 command, you should see a calendar presented in the terminal.

Installing for x86_64-efi platform.
Installation finished. No error reported.
No DKMS packages installed: not changing Secure Boot validation state.
Processing triggers for initramfs-tools (0.140)
update-initramfs: Generating /boot/initrd.img-5.10.0-27-cloud-amd64
Processing triggers for libc-bin (2.31-13+deb117) ...
Processing triggers for man-db (2.9.4-2) ...
Processing triggers for grub-cloud-amd64 (0.0.5) ...
Installing for i386-pc platform.
Installation finished. No error reported.
Installing for x86_64-efi platform.
Installation finished. No error reported.

debian@myfirstinstance:~$ sudo apt install ncal
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following NEW packages will be installed:
  ncal
0 upgraded, 1 newly installed, o to remove and 0 not upgraded.
Need to get 30.1 kB of archives.
After this operation, 69.6 kB of additional disk space will be used.
Get:1 http://deb.debian.org/debian bullseye/main amd64 ncal amd64 12.1.7+nmu3 |30.1 kB]
Fetched 30.1 kB in 0s (1748 kB/s)
Selecting previously unselected package ncal.
(Reading database ... 22362 files and directories currently installed.)
Preparing to unpack .../ncal_12.1.7+nmu3_amd64.deb ...
Unpacking ncal (12.1.7+nmu3) ...
Setting up ncal (12.1.7+nmu3) ...
Processing triggers for man-db (2.9.4-2) ...

debian@myfirstinstance:~$ cal
January 2024
Su Mo Tu We Th Fr Sa
    1  2  3  4  5  6
 7  8  9 10 11 12 13
14 15 16 17 18 19 20
21 22 23 24 25 26 27
28 29 30 31

debian@myfirstinstance:~$
Make a web server

We’ll start by creating a basic HTTP server with a simple "Hello World" homepage. You’ll do so by executing the following commands in a Linux VM:

mkdir public
cd public
echo Hello World > index.html
nohup sudo python3 -m http.server 80 &

At this point, your server should be up and running. You can verify that with curl:

$ curl http://localhost
Hello World

If you try the same command from your workstation against the external IP of your VM, i.e.,

$ curl http://{external IP of your VM}

you’ll notice that the command hangs and eventually times out. This is because the default firewall settings in the VM’s VPC allow inbound external connections only on certain ports.

To customize the firewall rules, navigate back to the instance details page for your VM, then click on the VPC name (it should be default if you have kept the advanced settings unchanged during instance creation).

Instance details page with the default VPC highlighted in the metadata table

There, you’ll see the Firewall Rules tab and a list of existing rules. Let’s take a look at the allow-ssh rule by clicking on the rule name.

VPC page

The rule is configured to allow inbound TCP connections on port 22 from any host. To allow your HTTP server to be accessible from anywhere, you can add a new rule that mimics the allow-ssh rule, except that it’ll have port 80 as the filter criteria.

First, click on New Rule and enter the following information:

  • Name: allow-http

  • Description: allow inbound TCP connections on port 80 from anywhere

  • Target:

    • Target Type: VPC

    • VPC Name: default (click Add Target after this)

  • Port Filter: 80 (click Add Port Filter after this)

  • Protocols: TCP

You can leave other fields with the default values and click Add Rule at the bottom of the form.

Now you can retry the curl command from your workstation and it should return "Hello World".

If you are running a different application that uses other port numbers, you can just replace 80 with the relevant port number or range in the rule. If you want to open multiple discrete ports, you can add them one at a time with Add Port Filter in a single rule. More information about firewall rules is available in the Guest Neworking guide.

Last updated