## What is this page? This page will walk you through how to set up a [JetStream2](https://docs.jetstream-cloud.org/) instance from start (no ACCESS account) to finish (working virtual machine). If you are set up already, you probably want one of the below. - ACCESS Allocations Website: https://allocations.access-ci.org/ - Exosphere Dashboard: https://jetstream2.exosphere.app/exosphere/ ### 1. Get approved for a "Credit Allocation" - Register as an ACCESS User for free: [here](https://operations.access-ci.org/identity/new-user) - You may need to wait a brief period to be approved. Once approved, move to the next step - Submit a request for an "ACCESS allocation" - These are essentially "compute credits" to utilize the computing resources. When they run out, the machine will be shut down. Fortunately, you can request more credits, etc. - Make sure that the "ACCESS Credits" box is checked in the form - The 200K credits (Explore Access allocation) are easy to get and require a short description of your project - Note that you will be listed as the PI by default - **If you are a student, you will also need a short "Letter of Collaboration" from your advisor.** - You will also need your CV, the CV of your advisor, and anyone else being added to the allocation - Approval will come via email, then check step 3 ### 2. Exchange credits for computing resources Now that you have credits, you need to exchange them for the computing resources you want from those that ACCESS offers. - Go to: https://allocations.access-ci.org/ - Find the "ALLOCATIONS" page (top left as of 2024-01-22) - Look for a button to "Exchange" your credits - There should be a dropdown box that says something like "New Action" > "Exchange" - Fill out the "Exchange" however you prefer. The below resources may be helpful: - [VM Sizes](https://docs.jetstream-cloud.org/general/vmsizes/) - [SU Budgeting/Storage](https://docs.jetstream-cloud.org/alloc/budgeting/#storage) - Wait for approval. Will come via email. ### 3. Creating an "instance" (virtual machine) Once your requested resources have been approved, you can set up a virtual machine (JetStream2 instance). You can check out the *many* resources available [here](https://docs.jetstream-cloud.org/), however, the gist is that you can create an instance by utilizing the Exosphere website (https://jetstream2.exosphere.app/exosphere/). - Go to https://jetstream2.exosphere.app/exosphere/ - Click "Add an allocation" - It will probably ask to link to your ACCESS account - Select the allocation that you just got approved - Look for a "Create" dropdown and then click "Instance" - Select "Ubuntu" as your Instance Source - Select the Flavor (machine size) based on computational needs (CPUs, RAM, etc.) - Make sure that "Enable web desktop" is checked as "Yes" - Select an SSH public key file that will provide you access to this machine - If you haven't added one to Exosphere already, follow the instructions that are there. - You should be copying and pasting you `id_rsa.pub` file, on your local machine. Should be saved at `~/.ssh/` - If you don't have an ssh key, read [this](https://www.ssh.com/academy/ssh/keygen). - Finish creating the instance - The system will require a few minutes to create everything. You can check on the status on your exosphere page. ### 4. Accessing your instance and adding users After your instance is "Ready," you will be able to remotely access the virtual machine. - You should be able to "click into" your instance details - I.e., just keep clicking your instance until it shows you all of the information about usage, etc. - Once there, look under the "Credentials" tab and you will find the IP address and a username (typically `exouser`) - You can then access the machine by going to your terminal and running: ```shell ssh exouser@ip_address ``` - Learn more about `ssh` [here](https://www.ssh.com) - The machine will already have the `id_rsa.pub` file that you provided when you created the instance. This lets you log in. - Next you need to create a user for yourself and potentially others ### Creating a new user ```shell sudo adduser <username> # Create the new user account sudo su - <username> # Switch to that user mkdir .ssh # Create the standard .ssh directory nano .ssh/authorized_keys # Add <username>'s id_rsa.pub key ``` Note the last line here uses `nano` which is a command that opens up a simple text editor. It will be blank (because you just created the file) and you should paste the key from the `id_rsa.pub` file associated with that user into the file. One key per line. ### Creating a new user with a data volume Sometimes you may want to attach a shared **data volume** to your instance/virtual machine. This allows you to have much more storage that is flexible and accessible by all users. This approach, however, requires an additional step — creating a "group" with specific permissions that (for example) allow people to access files that the others created, etc. This can be done easily by modifying the above code slightly lines. #### Create a group The first time you set up the machine, you will need to create the group and update the file permissions of your data volume directory. That can be done with the below. ```shell sudo groupadd <groupname> # Create the group sudo chgrp -R <groupname> <data_volume_directory> # See details below sudo chmod -R 2775 <data_volume_directory> # See details below ``` ** `sudo chgrp -R <groupname> <data_volume_directory>` ** - `chgrp`: This command changes the group ownership of a file or directory. - `-R`: This flag stands for "recursive." The command changes the group ownership of `<data_volume_directory>` and all of its contents to the group `<groupname>`. ** `sudo chmod -R 2775 <data_volume_directory>` ** - `chmod`: This command changes the file mode bits of a file or directory. - `-R`: Again, this flag indicates a recursive change for all files and directories within the specified path. - `2775`: These are the permissions you're setting. Let's break down what they mean: - The first digit `2` is a special set of permissions known as the "Set Group ID" (SGID). When set on a directory, it ensures that files created within the directory inherit their group from the directory, not from the user's current group. - The next digit `7` (which is `4` (read) + `2` (write) + `1` (execute)) sets full permissions (read, write, and execute) for the owner. - The second `7` sets full permissions for the group. - The last digit `5` (which is `4` (read) + `1` (execute)) sets read and execute permissions for others. This command sets the SGID on `<data_volume_directory>` and gives full permissions to the owner and group, and read/execute permissions to others, for `<data_volume_directory>` and all its contents. Combined, these commands are configuring the permissions and group ownership of the `<data_volume_directory>` directory and its contents, which is a common setup for shared directories in a multi-user environment. #### Create the user, add them to the group After that, the steps are the same, with one additional line that adds the user to the group. ```shell sudo adduser <username> sudo usermod -aG <groupname> <username> # Add the user to that group sudo su - <username> mkdir .ssh nano .ssh/authorized_keys ``` ### 5. Setting up your ssh `config` file The `ssh` command is wonderful because it can make switching between machines extremely easy. One hard thing to remember, however, is your machines IP address. You can alleviate this problem by creating a `config` file on your personal machine that remembers all of them for you! To do this, follow the steps below: - In your terminal, go to your `.ssh` folder on your personal computer. ```shell cd ~/.ssh # cd = change directory ``` - Create a file called `config` in that directory and store your the information for each virtual machine. It should look like the below. ``` ### JetStream2 Machines ### # ----------------------- # Host <your_chosen_easy_to_remember_name> HostName <IP ADDRESS> User <username> ### AWS Machines ### # ----------------------- # Host <different_easy_to_remember_name> HostName <DIFFERENT IP ADDRESS> User <username> ``` > Note: > 1. Anything following `#`s are ignored by ssh (commented out) so you can organize the file, if that suits you > 2. `ssh` is sensitive to tabs versus spaces, so if you pasted the above format into the your own, you may get weird errors. Can be better to type this out --- #### Related #academic_resources #programming