feat: improved 'server' module by explaining several modes of uploadi…

…ng data there

server.qmd

@@ -8,10 +8,18 @@ By the end of this module, you will be able to:
 
 - <u>Summarize</u> the primary steps for getting set up on a server
 - <u>Connect</u> your GitHub self with your server self
+- <u>Explain</u> at least one way of uploading data to a server
 
 ## Overview
 
-Working on [NCEAS' Server](https://aurora.nceas.ucsb.edu/) is similar to working on an entirely separate computer from the laptop or desktop computer on which you typically work. This means that you need to go through the steps of connecting GitHub to your "RStudio" again for the instance of RStudio accessed through Aurora. GitHub's Personal Access Token is referred to as "token" hereafter for simplicity.
+Working on [NCEAS' Server](https://aurora.nceas.ucsb.edu/) is similar to working on an entirely separate computer from the laptop or desktop computer on which you typically work. This means that you need to go through the steps of connecting GitHub to your "RStudio" again for the instance of RStudio accessed through Aurora. GitHub's Personal Access Token is referred to as "token" hereafter for simplicity. Note that our server also runs other analytical tools such as JupyterHub for python users.
+
+Often the reason to engage with the server is to increase the scale of your analyses far beyond what your personal computer can handle. There are other advantages such as:
+
+- **Storage Capacity** -- More disk space & faster storage
+- **Computing Power** -- More CPUs & RAM (384GB!!)
+- **Security** -- Nightly backups and data are distributed across multiple drives
+- **Collaboration** -- Shared data & consistent software versions accessible to everyone on your team
 
 ## Getting Started on the Server
 
@@ -31,9 +39,13 @@ The Terminal does not accept R syntax (and the Console doesn't accept Terminal s
 <img src="images/server/server-login-2-terminal.png" width="85%"/>
 </p>
 
-### Get your Invite Ready!
+### Get Invited!
+
+In order to access the server (and follow the instructions below) we'll need to create an account on the server for you. Please email [someone on our team](https://lter.github.io/scicomp/staff.html) or **[email protected]** so that we can contact NCEAS' IT team and get an invite email sent to you.
 
-After your group RSVP'd for this workshop, our team contacted NCEAS' IT team to get you an invite email to create an account on the server. An example of what that email may look like is included below but there are two key pieces of information:
+In that email, please include the name and email addresses of all of your team members who want to access the server. After that information has been received, NCEAS' IT team will create accounts for all of those people and will send you an invitation email to set up your account on the server.
+
+An example of what that email may look like is included below but there are two key pieces of information:
 
 1. Your username
 2. Your temporary password (covered by a **<span style="color:red">red bar</span>** in the screenshot).
@@ -99,3 +111,171 @@ usethis::git_default_branch_configure(name = "main")
 Once you're properly set up, working on the server should be completely seamless! Instead of opening RStudio on your computer you'll open a browser and work on the server from there but otherwise the feeling and process of version control should be identical. Eventually you may even want to make commits on your computer, push them to GitHub (after pulling!), then pull those same commits down to your server self and continue working there.
 
 You'll find working on the server to be dramatically faster for computationally-intense operations so we hope this guide has been helpful in getting you prepared to take advantage of that benefit!
+
+## Uploading Data to the Server
+
+### Via RStudio
+
+If you are uploading a single file, it may be most convenient to use RStudio's data upload capabilities. In the "Files" pane (default is top right but it may differ on your computer), you can click the button that is a white rectangle with a **<span style="color:gold">yellow</span>** circle with an upward facing arrow inside of it. In the below image the relevant button is in a **<span style="color:red">red</span>** square.
+
+<p align="center">
+<img src="images/server/server-upload-1.png" width="75%"/>
+</p>
+
+Clicking that button allows you to choose (1) where you want the uploaded file to go and (2) which file you want to upload.
+
+<p align="center">
+<img src="images/server/server-upload-2.png" width="75%"/>
+</p>
+
+You can also download data via the RStudio interface. To download a file, check the box next to it in the "Files" pane.
+
+<p align="center">
+<img src="images/server/server-download-1.png" width="75%"/>
+</p>
+
+Once the box is checked, click the gear icon then click the "Export..." option (about halfway down). In the image below this option is surrounded by a **<span style="color:red">red</span>** square
+
+<p align="center">
+<img src="images/server/server-download-2.png" width="75%"/>
+</p>
+
+In the resulting box you can choose to rename the file before downloading to your local computer. After renaming the file (or keeping its original name), click the "Download" button and the download should begin after a moment.
+
+<p align="center">
+<img src="images/server/server-download-3.png" width="65%"/>
+</p>
+
+These methods are effective for one or a few files being up/downloaded to the same directory but can quickly become cumbersome if you want to handle many files or a few files to several different folders.
+
+### Via sFTP Software
+
+If you want to upload or download many files we recommend using sFTP software (<u>s</u>ecure <u>F</u>ile <u>T</u>ransfer <u>P</u>rotocol). We use [Cyberduck](https://cyberduck.io/) internally, though there are alternatives like [WinSCP](https://winscp.net/eng/index.php). Both programs are free to use and more than capable of uploading and download many files to/from the server quickly and easily.
+
+Once you have installed one of these programs, you can sign in to the server from the sFTP program using your server username and password and can then upload or download files from your personal computer in the same way as you would move files among folders within your personal computer.
+
+#### Cyberduck Set Up Tutorial
+
+Here we briefly demonstrate how to set up a connection between Cyberduck and NCEAS' Server. Note that you must have already installed Cyberduck to follow these steps.
+
+1. In the Cyberduck window, click the "Open Connection" button with an icon of a globe with a plus sign. In the below image the button has a **<span style="color:red">red</span>** square around it.
+
+<p align="center">
+<img src="images/server/server-cyberduck-1.png" width="100%"/>
+</p>
+
+2. In the resulting window, input the following information:
+
+    - "Server" -- "aurora.nceas.ucsb.edu"
+    - "Username" -- whatever your username on the server is
+    - "Password" -- your password to the server
+    - "Port" -- change it to "22" (it will start as "21")
+
+<p align="center">
+<img src="images/server/server-cyberduck-2.png" width="85%"/>
+</p>
+
+3. Also, click the dropdown menu at the top that says "FTP (File Transfer Protocol) and select "SFTP (SSH File Transfer Protocol)" from the set of available options.
+
+<p align="center">
+<img src="images/server/server-cyberduck-3.png" width="85%"/>
+</p>
+
+4. Once you've input the above information, click the "Connect" button and you should have access to the server! You can now click around the different folders you have access to and upload or download from there.
+
+- To download: click the files/folders that you want and they should begin downloading to your personal computer
+- To upload: drag and drop the files where you want them
+
+### Via the Command Line
+
+If you are more comfortable with a CLI (<u>C</u>ommand <u>L</u>ine <u>I</u>nterface) you can also use that method of uploading/downloading. The command line includes the Terminal pane in RStudio, Terminal app for Macs, PuTTY, and gitBash among others. CLI can be a great tool to leverage filenames or types to filter specific files you would like to upload / download. Text in code chunks below are command line commands and any bracketed text `[like this]` should be replaced by some user-specific information before running.
+
+This portion of the tutorial is focused on using the command line to interact with the server. That said, if you're interested in the command line more generally or for other purposes, please reach out to [our team](https://lter.github.io/scicomp/staff.html)!
+
+#### CLI Option A: `scp`
+
+The `scp` command can be used to *upload* a file or folder from your computer to the server.
+
+1A. Navigate to the folder <u>on your computer</u> containing the file(s) you want to upload
+
+```{bash scp-1, eval = F}
+cd [folder]
+```
+
+- Note that if the folder name has spaces you'll need to "escape" the space by using a backslash (`\`)
+
+```{bash scp-2, eval = F}
+cd [folder\ name]
+```
+
+2A. Now you can upload that file to the server!
+
+```{bash scp-3, eval = F}
+scp [file_name] [user]@aurora.nceas.ucsb.edu:/[path/to/destination_folder/]
+```
+
+If instead you'd like to upload all of the files in a folder, do the following:
+
+1B. Navigate to the folder containing the folder on your computer you want to upload (using `cd`)
+
+```{bash scp-4, eval = F}
+cd [folder]
+```
+
+2B. Use `scp` with the recursive option (`-r`) to upload all of the files in that folder
+
+```{bash scp-5, eval = F}
+scp -r [folder] [user]@aurora.nceas.ucsb.edu:/[path/to/destination_folder/]
+```
+
+- Note that this uploads all of the files in the folder *not* the folder itself so you may want to create a new folder on the server to upload your local folder's contents into.
+
+Finally, note that you can also *download* files from the server to your local machine by simply switching the order of the machines:
+
+```{bash scp-6, eval = F}
+scp [user]@aurora.nceas.ucsb.edu:/[path/to/server_folder/file_name] [local_folder] 
+```
+
+#### CLI Option B: `sftp`
+
+The `get` command can be used to *download* a file.
+
+1. Connect to the server
+
+```{bash sftp-1, eval = F}
+sftp [user]@aurora.nceas.ucsb.edu:/home/shares
+```
+
+Your prompt at the shell should now have switched to `sftp>` and although it is the same window you are now looking at the files on the server! Try it by typing the `ls` command at the prompts. This will list all the files and folders within the `shares` folder on Aurora.
+
+2. Enter your group's folder in the `shares` folder
+
+```{bash sftp-2, eval = F}
+cd [your_group_folder]
+```
+
+3. If needed, continue using `cd` to get to the subfolder you want to access. Remember to "escape" any spaces in the folder name with backslashes!
+
+```{bash sftp-3, eval = F}
+cd [subfolder]
+```
+
+Note that most of the bash command will work, so you can use `ls` to list files and `pwd` to check your current path.
+
+4. When you are in the folder containing the file(s) you want, download the file you want
+
+```{bash sftp-4, eval = F}
+get [file_name_server]
+```
+
+5. You can also upload a local file to the server by using the `put` sFTP command
+
+```{bash sftp-5, eval = F}
+put [file_name_local]
+```
+
+6. When you are done downloading, close the connection to the server
+
+```{bash sftp-6, eval = F}
+exit
+```