From 867db9eac17739275cd4f617cecf00203d6fec10 Mon Sep 17 00:00:00 2001 From: Jesse Washburn <142361664+jessewashburn@users.noreply.github.com> Date: Thu, 12 Jun 2025 13:29:38 -0400 Subject: [PATCH 01/10] testing initial link to cloud vi --- index.md | 4 +++- pages/cloud-vi/firststeps.md | 1 + 2 files changed, 4 insertions(+), 1 deletion(-) create mode 100644 pages/cloud-vi/firststeps.md diff --git a/index.md b/index.md index 9066698fc..5342e7f26 100644 --- a/index.md +++ b/index.md @@ -17,6 +17,8 @@ Should you wish to reach out for information or assistance, feel free to contact --- #### Become a Virtual Intern! -Follow the [first steps](pages/vi/firststeps.md) in order to learn how. +Follow these first steps: +For hardware-based systems engineering: [first steps](pages/vi/firststeps.md). +For cloud-based systems engineering: [first steps](pages/cloud-vi/firststeps.md). **Find Us On:** [Linkedin](https://www.linkedin.com/company/open-learning-exchange) | [Twitter](https://twitter.com/oleorg) | [Facebook](https://www.facebook.com/openlearningexchange/) diff --git a/pages/cloud-vi/firststeps.md b/pages/cloud-vi/firststeps.md new file mode 100644 index 000000000..56f44d360 --- /dev/null +++ b/pages/cloud-vi/firststeps.md @@ -0,0 +1 @@ +HI \ No newline at end of file From ba1509a24fe8782d8d9183bea0309fbac595b6bd Mon Sep 17 00:00:00 2001 From: Jesse Washburn <142361664+jessewashburn@users.noreply.github.com> Date: Thu, 12 Jun 2025 14:12:13 -0400 Subject: [PATCH 02/10] first steps intro section --- pages/cloud-vi/firststeps.md | 236 ++++++++++++++++++++++++++++++++++- 1 file changed, 235 insertions(+), 1 deletion(-) diff --git a/pages/cloud-vi/firststeps.md b/pages/cloud-vi/firststeps.md index 56f44d360..e2e27e9ce 100644 --- a/pages/cloud-vi/firststeps.md +++ b/pages/cloud-vi/firststeps.md @@ -1 +1,235 @@ -HI \ No newline at end of file +# First Steps + +# The Big Picture + +Welcome to the first steps for becoming a Cloud Systems Engineering Virtual Intern at OLE! After completing these steps, you will be working on OLE’s core infrastructure projects such as Treehouses, Planet, and myPlanet. These first steps are a process to prove that you have learned the foundational skills before you can progress to working on harder projects with larger teams. Consider this to be the interview for the internship. + +If you are selected for the internship after completing the steps, you will be officially invited to join the OLE interns team! We’ll add you to the Virtual Interns Discord and assign you to a specific team to work on developing and improving OLE’s software. + +Once accepted, you and your team will work on an assignment, and we’ll switch up the assignments each week. As part of this internship, you will have the opportunity to work with software and languages including **[Git](https://git-scm.com/)**, **[GitHub](https://github.com/)**, **[Markdown](https://daringfireball.net/projects/markdown/syntax)**, **[Command Line/Terminal Scripts](https://www.codecademy.com/articles/command-line-commands)**, **[Vim](https://www.vim.org/)**, **[Typescript](https://www.typescriptlang.org/)**, **[CouchDB](https://couchdb.apache.org/)**, and **[Docker](https://www.docker.com/).** Furthermore, you will be able to learn and practice your skills in using **[Raspberry Pi Hardware](https://raspberrypi.org)** and **[Google Cloud VM](https://cloud.google.com/products/compute)**. + +The goal of OLE is to provide educational infrastructure to learners and educators in remote areas of the globe. The combination of Raspberry Pi and Cloud-based technologies are used in pursuit of this goal to provide a cost-effective means by which devices can access educational resources both online and offline. We aim to provide a stable system that is widely accessible by numerous devices and operating systems. This equipment will be deployed in the field with little or no access to the internet, so its reliability is of paramount importance. + + +**NOTE:** This is an unpaid but intensive internship that requires 20 hours of work each week. More information about the internship can be found in our [FAQ](faq.md#General_Internship_Questions). If you have further questions, don’t hesitate to ask other members in the Discord [chat](https://discord.com/channels/1079980988421132369/1229437557843169280)! + +# Pre-Requisites + +## Required Prerequisites +The following are the required hardware components that will be needed as part of the Virtual Intern placement. Software solutions such as containers are used by the Treehouses team to ensure that the solutions we develop work across computers and locations. However, as part of the Systems team, you will need some basic hardware of your own to make sure you can run, test and contribute to the software that the team is developing. + +### Hardware requirements: + +1. Raspberry Pi 4 or 5 ([Pi 4 information](https://www.raspberrypi.org/products/raspberry-pi-4-model-b/)) + - Any amount of RAM is acceptable (2GB minimum, 4GB+ recommended) + - Raspberry Pi 3B/3B+ also work, but Pi 4+ is recommended +1. Power supply for the Pi + - Pi 4: USB-C, 3.0A minimum + - Pi 3B+: Micro USB, 2.5A minimum +1. 3 microSD cards + - Minimum 16GB each + - U1 or Class 10 required +1. MicroSD card reader + - You will need a USB reader if your computer doesn't have an SD card slot +1. Laptop or computer with minimum 8GB of RAM + - You will need a Wi-Fi adapter if you are using a desktop without Wi-Fi capabilities. +1. Android device (phone or tablet) + - Memory (RAM): Minimum 2GB + - Operating System: + * Minimum: Android 10 "Q" + * Recommended: Android 12 + + **NOTE:** You can purchase all of these components together for your convenience (or if there are discounts) on places such as Amazon, eBay, etc... + +## Optional Hardware +There are also "optional" pieces of hardware that you can choose to purchase should you choose to, these are not compulsory for participation in the internship but may greatly assist you in developing your skills and contributing to the project. + +1. Ethernet cable - For Direct connection and troubleshooting of the Pi +1. [Real Time Clock (rtc)](https://www.amazon.com/s?k=raspberry+pi+rtc) +1. [Raspberry Pi 0W](https://www.raspberrypi.org/products/raspberry-pi-zero-w/) +1. Raspberry pi Camera(s): + - [Raspberry Pi Camera](https://www.raspberrypi.org/products/camera-module-v2/) + - [Raspberry Pi Night Vision Camera](https://www.raspberrypi.org/products/pi-noir-camera-v2/) + - [generic Raspberry Pi 5 Megapixel Camera](https://www.amazon.com/AuviPal-Megapixels-Raspberry-Camera-Module/dp/B07PQ63D2S/) +1. USB keyboard, mouse, monitor, and HDMI cable + +[Useful link for Rapberry Pi set up](https://www.youtube.com/watch?v=-9V4EpNNR6k) + +## Software Requirements + +In addition to the hardware listed above, you’ll need to install and configure software tools to support local and cloud-based development. These tools ensure your Pi, local machine, and cloud VM can all interoperate smoothly. + +### Required Software + +1. **Docker** + - Must be installed on your local machine and your Google Cloud VM. + - [Install Docker](https://docs.docker.com/get-docker/) + +2. **Node.js v14** + - Used to run the Planet application locally and on the VM. + - Install via [nvm](https://github.com/nvm-sh/nvm) or your platform’s package manager. + - Confirm with: `node -v` + +3. **Angular CLI v10** + - Required for building and running the Planet frontend. + - Install with: `npm install -g @angular/cli@10` + - Confirm with: `ng version` + +4. **Git + GitHub Account** + - Used to clone repositories and push your contributions. + - [Install Git](https://git-scm.com/downloads) + - [Create a GitHub account](https://github.com/join) if you don’t have one. + +5. **Google Cloud Platform (GCP) VM** + - You’ll be assigned or asked to create a Debian 12 virtual machine on Google Cloud. + - This will host a cloud instance of Planet, running Dockerized services like CouchDB and ChatAPI. + - Must have SSH access and Docker installed. + +6. **Fauxton (CouchDB Admin Interface)** + - Automatically included in CouchDB containers. + - Accessible at `http://localhost:2200/_utils` for development. + +7. **VS Code or other IDE with Git and SSH support** + +--- + +> These tools will allow you to run **Planet** on three networked systems: your local laptop, a Raspberry Pi, and a Google Cloud VM. This mirrors how OLE deployments work in the field and allows you to experiment with syncing data and communities across devices. + +--- + +# The Steps + +Social coding is a huge part of any open source and collaborative project, and [treehouses](https://github.com/treehouses) is no different. In the following series of steps, you will learn about Markdown, Docker, Bash, Vim, Git, GitHub, GitHub issues, and GitHub pull requests. + +Because these steps are simple, we expect high-quality work, which may take a longer time. We want to see that you are capable of using or learning how to use these tools (writing good GitHub issues, creating pull requests, using Markdown and Docker, etc.). These steps may seem easy, but we want you to impress us with good GitHub etiquette and quality Markdown. The bare minimum would be to just passively follow the steps; you should do further reading about the tools/languages we use so you can further your understanding and relieve confusion if you're unclear about how something works. **Treat these steps as learning opportunities!** The GitHub and Markdown skills you practice here are very important for both this internship and a future software development career. + +The MDwiki has plenty of resources to help you complete the steps. There is a list of useful links at the end of each step. We also created a [FAQ page](faq.md) where you can find the answers to some commonly asked questions. This page has even more [useful links and video tutorials](faq.md#Helpful_Links) that will help you become familiar with the tools/languages we use. For anything that is not on the FAQ page, Google and Stack Exchange are your friends :) + +**We also want you to keep us updated on a relatively good amount in the [Gitter chat](../chat.md) as you complete these steps. We will ask you to send us messages, links, and screenshots along the First Steps, and we will use this to track your progress, so please do not forget to do so.** + +A very large part of these steps is finding problems with these steps and this MDwiki, so take note of any issues that you run into or suggestions for improvement while doing these steps. + +There is no official deadline to complete these steps, but most candidates who are approved for the internship program finished the steps within 7-8 days. Good luck! + + +## Step 0 - Introductory Steps + +1. Complete the [New Virtual Intern Application form](http://apply.treehouses.io). If you have already done this after being invited to join the team then good job, you're all set! + +2. Log into your [GitHub account](https://github.com/) then watch [treehouses.github.io repo](https://github.com/treehouses/treehouses.github.io) and Follow [Dogi](https://github.com/dogi), [Ryan](https://github.com/indepthh), [Vassilis](https://github.com/vers4ce), [Roshan](https://github.com/rrijal53), [Sam](https://github.com/Liew211), [Samuel](https://github.com/samuelchen1213) and [Arran](https://github.com/ArranHL) on GitHub. + +In GitHub, we "[Watch](https://help.github.com/en/articles/watching-and-unwatching-repositories)" organization repositories and ["Follow"](https://help.github.com/en/articles/following-people) individuals. Look for the "Watch" button at the top right of the page when you are in a repository. Also, follow each other to see what others in the group are doing. (Click on the image to enlarge.) + +### Setting up your environment + +We interact with the Raspberry Pi via a command terminal, which is natively available for both Mac and Linux based systems. However, if you are on a Windows device, [Git Bash](https://git-scm.com/download/win) is highly recommended. + +### Working with Vi & Vim + +One of the most simple but most powerful text editors out there is Vim. If you want to see what Vim can do and how powerful it can be, you can learn more about Vim [here](https://danielmiessler.com/study/vim/#textobjects). Vim is not necessary for this internship but it is truly helpful when working on the Raspberry Pi not to have to download and install other text editors. + +**NOTE:** You can skip ahead to Step 3 while you are waiting for your Raspberry Pi to come in the mail. + +## Step 1 - Installing and Finding Your Raspberry Pi + +There are 3 sections in this step: +1. [Setting up your Raspberry Pi](pi-setup.md) +2. [Using treehouses Remote](treehouses-remote.md) +3. [Finding your Pi](find-pi.md) + + +## Step 2 - Use SSH and Tor to Remotely Control Your Raspberry Pi + +The Systems team uses SSH (Secure Shell) to securely and remotely control the Raspberry Pis we work with. SSH works by providing an admin protocol that allows users to control and modify their remote servers over the Internet. Follow the [Raspberry Pi SSH & Tor Tutorial](sshpi.md) to learn how. + + + +## Step 3 - Markdown and Fork Tutorial + +Follow the instructions on [GitHub and Markdown](githubandmarkdown.md) + +Make sure that you've linked to your github.io and pull request in the [Gitter chat](https://gitter.im/treehouses/Lobby). Also, include the `raw.githack` link in your pull request `https://raw.githack.com/YourUserName/YourUserName.github.io/YourBranchName/#!pages/vi/profiles/YourUserName.md` + +**NOTE**: The `raw.githack` link is case sensitive to your username. + + +> Once you complete Step 3 you will have: + +* 1 Pull request made + +Check your progress [here](trackprogress.md) + + +## Step 4 - System Tutorial + +### Vagrant + +Vagrant is an open-source software product for building and maintaining portable virtual software development environments. In this step, you will learn about how to interact with Vagrant through the command-line interface. +Follow the directions in the [Vagrant Tutorial](vagranttutorial.md) + +### Docker + +Docker is a computer program that performs operating-system-level virtualization also known as containerization. In this step, you will learn the basics of interacting with Docker and Docker Compose through the command-line interface and basic commands for maintaining your Planet installation. +Follow the directions in the [Docker Tutorial](dockertutorial.md) + + +## Step 5 - Keeping Fork Updated + +Follow the directions at [Git Repositories](gitrepositories.md) to keep your username.github.io and your local repository up to date. + + +## Step 6 - GitHub Issues Tutorial + +Follow the [GitHub Issues tutorial](github-issues.md) to create at least one issue. Post a link in [Gitter](https://gitter.im/treehouses/Lobby) whenever you create an issue or when you comment on someone else's issue. You are encouraged to post as many issues as you can for improving the page as well as for personal practice. No issue is too big or too small to be filed and it is OK if you are not sure how to fix it yourself. If you know how to solve an issue, be sure to provide a detailed account of your research and show how to fix it. It is ok to file an issue about minor typos and very small changes, but do not make this the case for all of the issues that you file. You can also work on issues that you didn't create. + +Make sure you have created at least one issue, resolved it, commented on an issue you didn't create and have a pull request with the fix merged. You may continue making Issues, Pull requests and Comments, or move on to the next step, while you are waiting for your pull request to be merged. The approval process for your Step 6 fix may take time, but it is OK to continue working. + +**NOTE**: When posting a link in the Gitter, it may be helpful to tag the newest interns since they are likely the most active. + +> Once you complete Step 6 you will have: + +* 2 pull requests made (one at step 3 and one at step 6) +* 1 comment added (on an issue you didn't create) +* 1 issue created + +Check your progress [here](trackprogress.md) + +Please note that creating and working on Issues are not exactly bound by the "Step" you are in. Feel free to move on to other steps, and make more Issues and Pull Requests while you wait on OLE approval for your merge(s). + + +## Step 7 - Other Services Running from a Raspberry Pi + +### Nextcloud over Tor + +Follow the [Nextcloud and Tor Tutorial](nextcloud-tor.md) to set up the Nextcloud service on your Pi, and access it via Tor. + + +## Step 8 - Create Issues and Pull Requests + +In this step, we will adopt the motto of "Practice makes Perfect". You will follow the same steps as in **Step 6**, continuing to improve this Markdown Wiki so that it is educational, yet easy to understand for future interns. + +You should: + +* Add comments to three issues other than your own (somebody else's issue) +* Create three new issues (in addition to those you have already created in previous steps) + * Get approval to work on the issues you have created. **Make sure someone from the System's team confirms that you should work on the issue BEFORE you start to work on it.** +* Resolve the three issues by making the necessary changes in your repo with three separate pull requests. + +Just as your learning with this Wiki was made possible by the efforts of previous interns, now we turn to you to continue that tradition and help future interns take their First Steps. Through this step, you should try to further improve our Markdown Wiki, with better explanations, formatting fixes, and more! You must have made your pull requests and have them each approved by at least two other OLE team members/interns in order for it to be merged to the upstream repository. Just as before, announce your Pull Request on the Gitter chat so other members can review it. You may need to make some additional corrections. Learn by teaching - or editing our teaching tool, in this case! + +**NOTE**: When you are fixing an issue, mention the issue number you are fixing in the title of your pull request and make a new branch for every new issue from the master branch. + +> Once you complete Step 8, you should have: + +* 5 merged pull requests (one at step 3, one at step 6 and three at step 8) +* 4 comments made on *issues you didn't create* (one at step 6 and three at step 8) +* 4 issues created (one at step 6 and three at step 8) + +**NOTE**: You can track your progress with the number of pull requests and issues [here](trackprogress.md). + +## Step 9 - Be Part of the Team + +Next thing is to post a screenshot of your completed progress to the Gitter chat room. Click [here](trackprogress.md) to find your completed progress. +Message us ("@/all" and "@dogi") and ask about adding yourself to the virtual intern list found in [team.md](team.md) and setting up a meeting so you can become a part of the team as soon as possible. + +Make sure to read through the [intern orientation document](orientation.md) before the meeting. From 6657a5b1a752c875d0300a0ded312dd7c3f521bf Mon Sep 17 00:00:00 2001 From: Jesse Washburn <142361664+jessewashburn@users.noreply.github.com> Date: Thu, 12 Jun 2025 15:13:02 -0400 Subject: [PATCH 03/10] draft of VM installation steps --- pages/cloud-vi/firststeps.md | 152 ++++++++++++++++++++++++++++++----- 1 file changed, 133 insertions(+), 19 deletions(-) diff --git a/pages/cloud-vi/firststeps.md b/pages/cloud-vi/firststeps.md index e2e27e9ce..bf4e9d781 100644 --- a/pages/cloud-vi/firststeps.md +++ b/pages/cloud-vi/firststeps.md @@ -20,7 +20,7 @@ The following are the required hardware components that will be needed as part o ### Hardware requirements: -1. Raspberry Pi 4 or 5 ([Pi 4 information](https://www.raspberrypi.org/products/raspberry-pi-4-model-b/)) +1. Raspberry Pi 4 or 5 ([Pi 5 information](https://www.raspberrypi.com/products/raspberry-pi-5/)) - Any amount of RAM is acceptable (2GB minimum, 4GB+ recommended) - Raspberry Pi 3B/3B+ also work, but Pi 4+ is recommended 1. Power supply for the Pi @@ -105,7 +105,7 @@ Because these steps are simple, we expect high-quality work, which may take a lo The MDwiki has plenty of resources to help you complete the steps. There is a list of useful links at the end of each step. We also created a [FAQ page](faq.md) where you can find the answers to some commonly asked questions. This page has even more [useful links and video tutorials](faq.md#Helpful_Links) that will help you become familiar with the tools/languages we use. For anything that is not on the FAQ page, Google and Stack Exchange are your friends :) -**We also want you to keep us updated on a relatively good amount in the [Gitter chat](../chat.md) as you complete these steps. We will ask you to send us messages, links, and screenshots along the First Steps, and we will use this to track your progress, so please do not forget to do so.** +**We also want you to keep us updated regularly in the [Discord chat](https://discord.com/channels/1079980988421132369/1229437557843169280) as you complete these steps. We will ask you to send us messages, links, and screenshots along the First Steps, and we will use this to track your progress, so please do not forget to do so.** A very large part of these steps is finding problems with these steps and this MDwiki, so take note of any issues that you run into or suggestions for improvement while doing these steps. @@ -116,7 +116,7 @@ There is no official deadline to complete these steps, but most candidates who a 1. Complete the [New Virtual Intern Application form](http://apply.treehouses.io). If you have already done this after being invited to join the team then good job, you're all set! -2. Log into your [GitHub account](https://github.com/) then watch [treehouses.github.io repo](https://github.com/treehouses/treehouses.github.io) and Follow [Dogi](https://github.com/dogi), [Ryan](https://github.com/indepthh), [Vassilis](https://github.com/vers4ce), [Roshan](https://github.com/rrijal53), [Sam](https://github.com/Liew211), [Samuel](https://github.com/samuelchen1213) and [Arran](https://github.com/ArranHL) on GitHub. +2. Log into your [GitHub account](https://github.com/) then watch [treehouses.github.io repo](https://github.com/treehouses/treehouses.github.io) and Follow [Dogi](https://github.com/dogi) and [Jesse](https://github.com/jessewashburn) on GitHub. In GitHub, we "[Watch](https://help.github.com/en/articles/watching-and-unwatching-repositories)" organization repositories and ["Follow"](https://help.github.com/en/articles/following-people) individuals. Look for the "Watch" button at the top right of the page when you are in a repository. Also, follow each other to see what others in the group are doing. (Click on the image to enlarge.) @@ -124,13 +124,136 @@ In GitHub, we "[Watch](https://help.github.com/en/articles/watching-and-unwatchi We interact with the Raspberry Pi via a command terminal, which is natively available for both Mac and Linux based systems. However, if you are on a Windows device, [Git Bash](https://git-scm.com/download/win) is highly recommended. -### Working with Vi & Vim +### Working with Vi & Vim (Optional) -One of the most simple but most powerful text editors out there is Vim. If you want to see what Vim can do and how powerful it can be, you can learn more about Vim [here](https://danielmiessler.com/study/vim/#textobjects). Vim is not necessary for this internship but it is truly helpful when working on the Raspberry Pi not to have to download and install other text editors. +Vim is a lightweight and powerful terminal-based text editor. It's especially useful when working directly on the Raspberry Pi or virtual machines where graphical interfaces may not be available. + +- Learn more about Vim [here](https://danielmiessler.com/study/vim/#textobjects) +- Practice using Vim in your terminal by typing `vimtutor` + +While Vim is optional, learning it can make you more efficient in low-resource environments. + +### Recommended Alternative: Visual Studio Code (VS Code) + +For local development, debugging, and remote access to your Pi or Google VM, [Visual Studio Code](https://code.visualstudio.com/) is a highly recommended editor. With extensions like: + +- **Remote - SSH** (for editing files on your Pi or VM) +- **Prettier** (for formatting code) +- **GitHub** (for pushing/pulling code) + +VS Code offers a user-friendly and powerful coding environment. + +> If you're more comfortable in a GUI editor, go with VS Code. If you're curious about terminal power tools, give Vim a shot. **NOTE:** You can skip ahead to Step 3 while you are waiting for your Raspberry Pi to come in the mail. -## Step 1 - Installing and Finding Your Raspberry Pi +## Step 1 - Setting up your Google Cloud VM + +### ✅ Prerequisites + +- A Google account +- Basic familiarity with terminal commands + +### 1. Create a Google Cloud Project + +1. Go to [https://console.cloud.google.com](https://console.cloud.google.com) +2. In the top navigation bar, click the project dropdown and choose **"New Project"** +3. Give it a name (e.g. `ole-vm`) and click **Create** + +### 2. Enable Billing (Required) + +If you haven't already, enable billing on your GCP account. +- You can use the **Free Tier** which includes 90-day, $300 trial credit +- A credit card is required for signup but won't be charged without usage beyond free limits + +### 3. Enable Compute Engine + +1. In the left-hand menu, go to **Compute Engine → VM Instances** +2. Click **"Enable"** to activate the API + +### 4. Create a Virtual Machine + +1. Click **"Create Instance"** +2. Use these recommended settings: + - **Name**: `ole-vm` + - **Region**: `us-east1` or your nearest region + - **Machine type**: `e2-medium` (2 vCPU, 4 GB RAM) + - **Boot disk**: + - Image: `Debian 12 (Bookworm)` + - **Firewall**: + - Check **Allow HTTP** + - Check **Allow HTTPS** +3. Click **"Create"** + +### 5. Connect to Your VM via SSH + +Once your VM is running, you can connect to it in **three different ways** depending on your preference and development workflow. + +### ✅ Option 1: Use the Web SSH Console (Browser-Based) + +1. Visit [https://console.cloud.google.com](https://console.cloud.google.com) +2. Navigate to **Compute Engine → VM Instances** +3. Click the **"SSH"** button next to your VM to open a terminal directly in your browser. + +This is the simplest option and requires no setup on your computer. + +--- + +### ✅ Option 2: Use Your Local Terminal + +You must first install the [Google Cloud SDK (gcloud CLI)](https://cloud.google.com/sdk/docs/install) if you haven’t already. + +Then, use the following command to connect from your terminal: + +``` +gcloud compute ssh ole-vm --zone=us-east1-b +``` + +> Replace `us-east1-b` with your actual zone if different. + +This method allows fast access for command-line tasks directly from your development machine. + +--- + +### ✅ Option 3: Use Visual Studio Code with Remote-SSH + +This is the recommended method. + +#### Prerequisites: + +- [Visual Studio Code](https://code.visualstudio.com/) +- Install the **Remote - SSH** extension + https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh +- (Optional) Install the **Remote Explorer** extension + https://marketplace.visualstudio.com/items?itemName=ms-vscode.remote-explorer + +#### Steps: + +1. Open VS Code +2. Press `Ctrl+Shift+P` or `Cmd+Shift+P` to open the **Command Palette** +3. Choose: + ``` + Remote-SSH: Connect to Host... + ``` +4. Enter the external IP address of your VM (visible in the Compute Engine VM list) +5. Select your SSH identity file if prompted (`.ssh` private key) +6. VS Code will connect and open a remote window where you can edit and manage files as if they were local. + +> 💡 Pro Tip: Save your VM in `~/.ssh/config` to reuse it easily. + +Example `~/.ssh/config` entry: + +``` +Host ole-vm + HostName YOUR_VM_IP + User YOUR_USERNAME + IdentityFile ~/.ssh/YOUR_KEY +``` + +--- + +## Step 2 - Installing and Finding Your Raspberry Pi +**NOTE:** You can skip ahead to Step 4 while you are waiting for your Raspberry Pi to come in the mail. There are 3 sections in this step: 1. [Setting up your Raspberry Pi](pi-setup.md) @@ -138,13 +261,12 @@ There are 3 sections in this step: 3. [Finding your Pi](find-pi.md) -## Step 2 - Use SSH and Tor to Remotely Control Your Raspberry Pi +## Step 3 - Use SSH and Tor to Remotely Control Your Raspberry Pi The Systems team uses SSH (Secure Shell) to securely and remotely control the Raspberry Pis we work with. SSH works by providing an admin protocol that allows users to control and modify their remote servers over the Internet. Follow the [Raspberry Pi SSH & Tor Tutorial](sshpi.md) to learn how. - -## Step 3 - Markdown and Fork Tutorial +## Step 4 - Markdown and Fork Tutorial Follow the instructions on [GitHub and Markdown](githubandmarkdown.md) @@ -160,12 +282,7 @@ Make sure that you've linked to your github.io and pull request in the [Gitter c Check your progress [here](trackprogress.md) -## Step 4 - System Tutorial - -### Vagrant - -Vagrant is an open-source software product for building and maintaining portable virtual software development environments. In this step, you will learn about how to interact with Vagrant through the command-line interface. -Follow the directions in the [Vagrant Tutorial](vagranttutorial.md) +## Step 5 - System Tutorial ### Docker @@ -173,13 +290,10 @@ Docker is a computer program that performs operating-system-level virtualization Follow the directions in the [Docker Tutorial](dockertutorial.md) -## Step 5 - Keeping Fork Updated +## Step 6 - GitHub Issues Tutorial Follow the directions at [Git Repositories](gitrepositories.md) to keep your username.github.io and your local repository up to date. - -## Step 6 - GitHub Issues Tutorial - Follow the [GitHub Issues tutorial](github-issues.md) to create at least one issue. Post a link in [Gitter](https://gitter.im/treehouses/Lobby) whenever you create an issue or when you comment on someone else's issue. You are encouraged to post as many issues as you can for improving the page as well as for personal practice. No issue is too big or too small to be filed and it is OK if you are not sure how to fix it yourself. If you know how to solve an issue, be sure to provide a detailed account of your research and show how to fix it. It is ok to file an issue about minor typos and very small changes, but do not make this the case for all of the issues that you file. You can also work on issues that you didn't create. Make sure you have created at least one issue, resolved it, commented on an issue you didn't create and have a pull request with the fix merged. You may continue making Issues, Pull requests and Comments, or move on to the next step, while you are waiting for your pull request to be merged. The approval process for your Step 6 fix may take time, but it is OK to continue working. From 28c8aa85d54e02250377dfeac1f07cd5b27fb17f Mon Sep 17 00:00:00 2001 From: Jesse Washburn <142361664+jessewashburn@users.noreply.github.com> Date: Thu, 12 Jun 2025 15:58:42 -0400 Subject: [PATCH 04/10] more raspberry pi instructions. updated vm instructions --- pages/cloud-vi/firststeps.md | 220 ++++++++++++++++++++++------------- 1 file changed, 140 insertions(+), 80 deletions(-) diff --git a/pages/cloud-vi/firststeps.md b/pages/cloud-vi/firststeps.md index bf4e9d781..1fa9e41f2 100644 --- a/pages/cloud-vi/firststeps.md +++ b/pages/cloud-vi/firststeps.md @@ -149,107 +149,168 @@ VS Code offers a user-friendly and powerful coding environment. ## Step 1 - Setting up your Google Cloud VM -### ✅ Prerequisites +This step will walk you through creating a virtual machine (VM) on Google Cloud Platform (GCP), configuring it securely, and preparing it for Planet development. -- A Google account -- Basic familiarity with terminal commands +--- -### 1. Create a Google Cloud Project +### 1. Enable Required APIs -1. Go to [https://console.cloud.google.com](https://console.cloud.google.com) -2. In the top navigation bar, click the project dropdown and choose **"New Project"** -3. Give it a name (e.g. `ole-vm`) and click **Create** +1. Go to [Google Cloud Console](https://console.cloud.google.com/) +2. In the top search bar, search for **Compute Engine API** +3. Click into it, and click **Enable** +4. Wait for it to activate (this may take a few moments) -### 2. Enable Billing (Required) +--- -If you haven't already, enable billing on your GCP account. -- You can use the **Free Tier** which includes 90-day, $300 trial credit -- A credit card is required for signup but won't be charged without usage beyond free limits +### 2. Add Your SSH Public Key -### 3. Enable Compute Engine +1. Search for **"Metadata"** +2. Click **"Metadata"** under **Compute Engine** +3. Navigate to the **"SSH KEYS"** tab +4. Click **"Edit"**, then **"Add Item"** +5. Paste your full public SSH key, formatted like: -1. In the left-hand menu, go to **Compute Engine → VM Instances** -2. Click **"Enable"** to activate the API + ``` + ssh-ed25519 AAAAC3... yourusername + ``` -### 4. Create a Virtual Machine + > You must append a space and your **username** at the end of the key to satisfy Google Cloud’s required format. + +6. Share your key with the team via Discord +--- + +### 3. Create the VM Instance + +1. In the console, go to **Compute Engine > VM Instances** +2. Click **"Create Instance"** +3. Use the following settings: -1. Click **"Create Instance"** -2. Use these recommended settings: - **Name**: `ole-vm` - - **Region**: `us-east1` or your nearest region - - **Machine type**: `e2-medium` (2 vCPU, 4 GB RAM) - - **Boot disk**: + - **Region**: Select one near you (e.g., `us-east1`) + - **Machine Type**: `e2-medium` (2 vCPU, 4 GB RAM) + - **Boot Disk**: - Image: `Debian 12 (Bookworm)` - **Firewall**: - - Check **Allow HTTP** - - Check **Allow HTTPS** -3. Click **"Create"** + - ✅ Check **Allow HTTP** + - ✅ Check **Allow HTTPS** -### 5. Connect to Your VM via SSH +4. Leave all other settings as defaults +5. Click **"Create"** -Once your VM is running, you can connect to it in **three different ways** depending on your preference and development workflow. +> The VM will typically cost $25–$35/month depending on location and usage. -### ✅ Option 1: Use the Web SSH Console (Browser-Based) +--- -1. Visit [https://console.cloud.google.com](https://console.cloud.google.com) -2. Navigate to **Compute Engine → VM Instances** -3. Click the **"SSH"** button next to your VM to open a terminal directly in your browser. +### 4. Create Firewall Rule -This is the simplest option and requires no setup on your computer. +1. In the console, search for **"Firewall"** and go to **VPC Network > Firewall** +2. Click **"CREATE FIREWALL RULE"** +3. Set the following: + + - **Name**: `planetdev-rules` + - **Targets**: All instances in the network + - **Source IPv4 Ranges**: `0.0.0.0/0` + - **Protocols and ports**: + - ✅ Check TCP + - Ports: `2200,3000,5000` + +4. Click **"Create"** --- -### ✅ Option 2: Use Your Local Terminal +### 5. SSH Into the VM -You must first install the [Google Cloud SDK (gcloud CLI)](https://cloud.google.com/sdk/docs/install) if you haven’t already. +You can SSH into your VM in **three different ways**: -Then, use the following command to connect from your terminal: +#### Option A: Google Cloud Console -``` -gcloud compute ssh ole-vm --zone=us-east1-b +- Go to **Compute Engine** +- Click the **SSH** button next to your VM + +#### Option B: Local Terminal (with SSH key) + +```bash +ssh -i ~/.ssh/id_ed25519 yourusername@ ``` -> Replace `us-east1-b` with your actual zone if different. +#### Option C: VS Code with Remote SSH -This method allows fast access for command-line tasks directly from your development machine. +1. Install **Remote - SSH** extension in VS Code +2. In the Command Palette: + `Remote-SSH: Connect to Host...` +3. Enter your VM's external IP and SSH key when prompted --- -### ✅ Option 3: Use Visual Studio Code with Remote-SSH +### 6. Install Required Tools on Your VM -This is the recommended method. +Connect to the VM and run: -#### Prerequisites: +```bash +sudo apt-get update && sudo apt-get install git unzip +``` -- [Visual Studio Code](https://code.visualstudio.com/) -- Install the **Remote - SSH** extension - https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh -- (Optional) Install the **Remote Explorer** extension - https://marketplace.visualstudio.com/items?itemName=ms-vscode.remote-explorer +Then follow Docker’s Debian installation guide here: +https://docs.docker.com/engine/install/debian/#install-using-the-repository -#### Steps: +> You can also reference: +> https://open-learning-exchange.github.io/#!pages/vi/vi-docker-development-tutorial.md -1. Open VS Code -2. Press `Ctrl+Shift+P` or `Cmd+Shift+P` to open the **Command Palette** -3. Choose: - ``` - Remote-SSH: Connect to Host... - ``` -4. Enter the external IP address of your VM (visible in the Compute Engine VM list) -5. Select your SSH identity file if prompted (`.ssh` private key) -6. VS Code will connect and open a remote window where you can edit and manage files as if they were local. +--- + +### ✅ 7. Node.js and Angular Setup -> 💡 Pro Tip: Save your VM in `~/.ssh/config` to reuse it easily. +> ⚠️ Important: **Do not install Node.js as root.** Use your regular user account. -Example `~/.ssh/config` entry: +Install Node.js v14 and Angular CLI v10: +```bash +curl -fsSL https://deb.nodesource.com/setup_14.x | sudo -E bash - +sudo apt-get install -y nodejs +npm install -g @angular/cli@10 ``` -Host ole-vm - HostName YOUR_VM_IP - User YOUR_USERNAME - IdentityFile ~/.ssh/YOUR_KEY + +Then follow the official tutorial to install and configure the Planet development environment: + +[Planet Docker Development Tutorial](https://open-learning-exchange.github.io/#!pages/vi/vi-docker-development-tutorial.md) + +This includes: + +- Downloading the Planet dev Docker config +- Running CouchDB and ChatAPI services +- Setting up CouchDB with CORS +- Cloning and configuring the `planet` repo + +Make sure to complete that guide before moving to the next step. + +--- + +### 8. Running Planet in the Background + +Start a `screen` session to keep the frontend running after you disconnect: + +```bash +screen +ng serve ``` +Once the frontend is running, press `Ctrl + A`, then `D` to detach. + +--- + +### 9. Planet Configuration + +- When configuring your Planet instance in the browser, choose **Nation** (not Community) +- Avoid common passwords like `12345`, `admin`, etc. + +--- + +### ✅ 10. Share Access + +- Send your VM **external IP address** and CouchDB **username/password** to your team +- Your VM is now part of the development network! + + --- ## Step 2 - Installing and Finding Your Raspberry Pi @@ -266,31 +327,37 @@ There are 3 sections in this step: The Systems team uses SSH (Secure Shell) to securely and remotely control the Raspberry Pis we work with. SSH works by providing an admin protocol that allows users to control and modify their remote servers over the Internet. Follow the [Raspberry Pi SSH & Tor Tutorial](sshpi.md) to learn how. -## Step 4 - Markdown and Fork Tutorial +## Step 4 - System Tutorial -Follow the instructions on [GitHub and Markdown](githubandmarkdown.md) +### Docker -Make sure that you've linked to your github.io and pull request in the [Gitter chat](https://gitter.im/treehouses/Lobby). Also, include the `raw.githack` link in your pull request `https://raw.githack.com/YourUserName/YourUserName.github.io/YourBranchName/#!pages/vi/profiles/YourUserName.md` +Docker is a computer program that performs operating-system-level virtualization also known as containerization. In this step, you will learn the basics of interacting with Docker and Docker Compose through the command-line interface and basic commands for maintaining your Planet installation. +Follow the directions in the [Docker Tutorial](dockertutorial.md) -**NOTE**: The `raw.githack` link is case sensitive to your username. +## Step 5 - Other Services Running from a Raspberry Pi -> Once you complete Step 3 you will have: +### Nextcloud over Tor -* 1 Pull request made +Follow the [Nextcloud and Tor Tutorial](nextcloud-tor.md) to set up the Nextcloud service on your Pi, and access it via Tor. -Check your progress [here](trackprogress.md) +## Step 6 - Markdown and Fork Tutorial -## Step 5 - System Tutorial +Follow the instructions on [GitHub and Markdown](githubandmarkdown.md) -### Docker +Make sure that you've linked to your github.io and pull request in the [Discord [chat](https://discord.com/channels/1079980988421132369/1229437557843169280)]. Also, include the `raw.githack` link in your pull request `https://raw.githack.com/YourUserName/YourUserName.github.io/YourBranchName/#!pages/vi/profiles/YourUserName.md` -Docker is a computer program that performs operating-system-level virtualization also known as containerization. In this step, you will learn the basics of interacting with Docker and Docker Compose through the command-line interface and basic commands for maintaining your Planet installation. -Follow the directions in the [Docker Tutorial](dockertutorial.md) +**NOTE**: The `raw.githack` link is case sensitive to your username. + +> Once you complete Step 3 you will have: + +* 1 Pull request made + +Check your progress [here](trackprogress.md) -## Step 6 - GitHub Issues Tutorial +## Step 7 - GitHub Issues Tutorial Follow the directions at [Git Repositories](gitrepositories.md) to keep your username.github.io and your local repository up to date. @@ -311,13 +378,6 @@ Check your progress [here](trackprogress.md) Please note that creating and working on Issues are not exactly bound by the "Step" you are in. Feel free to move on to other steps, and make more Issues and Pull Requests while you wait on OLE approval for your merge(s). -## Step 7 - Other Services Running from a Raspberry Pi - -### Nextcloud over Tor - -Follow the [Nextcloud and Tor Tutorial](nextcloud-tor.md) to set up the Nextcloud service on your Pi, and access it via Tor. - - ## Step 8 - Create Issues and Pull Requests In this step, we will adopt the motto of "Practice makes Perfect". You will follow the same steps as in **Step 6**, continuing to improve this Markdown Wiki so that it is educational, yet easy to understand for future interns. From 842ec8119261b0f18155b6c45f0bc8d15d5e1e20 Mon Sep 17 00:00:00 2001 From: Jesse Washburn <142361664+jessewashburn@users.noreply.github.com> Date: Fri, 13 Jun 2025 12:47:12 -0400 Subject: [PATCH 05/10] moved vm setup to its own page --- pages/cloud-vi/firststeps.md | 213 ++++++----------------------------- pages/cloud-vi/vm-setup | 184 ++++++++++++++++++++++++++++++ 2 files changed, 216 insertions(+), 181 deletions(-) create mode 100644 pages/cloud-vi/vm-setup diff --git a/pages/cloud-vi/firststeps.md b/pages/cloud-vi/firststeps.md index 1fa9e41f2..d4d11cc4e 100644 --- a/pages/cloud-vi/firststeps.md +++ b/pages/cloud-vi/firststeps.md @@ -24,8 +24,8 @@ The following are the required hardware components that will be needed as part o - Any amount of RAM is acceptable (2GB minimum, 4GB+ recommended) - Raspberry Pi 3B/3B+ also work, but Pi 4+ is recommended 1. Power supply for the Pi - - Pi 4: USB-C, 3.0A minimum - - Pi 3B+: Micro USB, 2.5A minimum + - Pi 4+: USB-C, 3.0A minimum + - Pi 3: Micro USB, 2.5A minimum 1. 3 microSD cards - Minimum 16GB each - U1 or Class 10 required @@ -57,39 +57,31 @@ There are also "optional" pieces of hardware that you can choose to purchase sho ## Software Requirements -In addition to the hardware listed above, you’ll need to install and configure software tools to support local and cloud-based development. These tools ensure your Pi, local machine, and cloud VM can all interoperate smoothly. +In addition to the hardware listed above, you’ll need to install and configure software tools to support local and cloud-based development. These tools ensure your Pi, local machine, and cloud VM can all interoperate smoothly. Detailed installation structures will be provided in later steps. ### Required Software 1. **Docker** - Must be installed on your local machine and your Google Cloud VM. - - [Install Docker](https://docs.docker.com/get-docker/) 2. **Node.js v14** - Used to run the Planet application locally and on the VM. - - Install via [nvm](https://github.com/nvm-sh/nvm) or your platform’s package manager. - - Confirm with: `node -v` 3. **Angular CLI v10** - Required for building and running the Planet frontend. - - Install with: `npm install -g @angular/cli@10` - - Confirm with: `ng version` 4. **Git + GitHub Account** - Used to clone repositories and push your contributions. - - [Install Git](https://git-scm.com/downloads) - - [Create a GitHub account](https://github.com/join) if you don’t have one. 5. **Google Cloud Platform (GCP) VM** - - You’ll be assigned or asked to create a Debian 12 virtual machine on Google Cloud. + - You’ll be asked to create a Debian 12 virtual machine on Google Cloud. - This will host a cloud instance of Planet, running Dockerized services like CouchDB and ChatAPI. - Must have SSH access and Docker installed. 6. **Fauxton (CouchDB Admin Interface)** - Automatically included in CouchDB containers. - - Accessible at `http://localhost:2200/_utils` for development. -7. **VS Code or other IDE with Git and SSH support** +7. **VIM, VS Code or other IDE with Git and SSH support** --- @@ -145,204 +137,63 @@ VS Code offers a user-friendly and powerful coding environment. > If you're more comfortable in a GUI editor, go with VS Code. If you're curious about terminal power tools, give Vim a shot. -**NOTE:** You can skip ahead to Step 3 while you are waiting for your Raspberry Pi to come in the mail. - -## Step 1 - Setting up your Google Cloud VM - -This step will walk you through creating a virtual machine (VM) on Google Cloud Platform (GCP), configuring it securely, and preparing it for Planet development. - ---- - -### 1. Enable Required APIs - -1. Go to [Google Cloud Console](https://console.cloud.google.com/) -2. In the top search bar, search for **Compute Engine API** -3. Click into it, and click **Enable** -4. Wait for it to activate (this may take a few moments) - --- -### 2. Add Your SSH Public Key +## Step 1 – Set Up Your Cloud VM -1. Search for **"Metadata"** -2. Click **"Metadata"** under **Compute Engine** -3. Navigate to the **"SSH KEYS"** tab -4. Click **"Edit"**, then **"Add Item"** -5. Paste your full public SSH key, formatted like: +To begin, you’ll set up a Debian-based virtual machine on Google Cloud. This VM will serve as your cloud-hosted Planet node and is a key part of the networked development environment. - ``` - ssh-ed25519 AAAAC3... yourusername - ``` +Follow the full setup instructions here: +👉 [pages/cloud-vi/vm-setup.md](pages/cloud-vi/vm-setup.md) - > You must append a space and your **username** at the end of the key to satisfy Google Cloud’s required format. +Once complete, you’ll have a persistent, internet-accessible system ready to run Docker containers, host Planet, and connect with your Raspberry Pi and local machine. -6. Share your key with the team via Discord --- -### 3. Create the VM Instance - -1. In the console, go to **Compute Engine > VM Instances** -2. Click **"Create Instance"** -3. Use the following settings: - - - **Name**: `ole-vm` - - **Region**: Select one near you (e.g., `us-east1`) - - **Machine Type**: `e2-medium` (2 vCPU, 4 GB RAM) - - **Boot Disk**: - - Image: `Debian 12 (Bookworm)` - - **Firewall**: - - ✅ Check **Allow HTTP** - - ✅ Check **Allow HTTPS** - -4. Leave all other settings as defaults -5. Click **"Create"** - -> The VM will typically cost $25–$35/month depending on location and usage. - ---- - -### 4. Create Firewall Rule - -1. In the console, search for **"Firewall"** and go to **VPC Network > Firewall** -2. Click **"CREATE FIREWALL RULE"** -3. Set the following: - - - **Name**: `planetdev-rules` - - **Targets**: All instances in the network - - **Source IPv4 Ranges**: `0.0.0.0/0` - - **Protocols and ports**: - - ✅ Check TCP - - Ports: `2200,3000,5000` - -4. Click **"Create"** - ---- - -### 5. SSH Into the VM - -You can SSH into your VM in **three different ways**: - -#### Option A: Google Cloud Console - -- Go to **Compute Engine** -- Click the **SSH** button next to your VM - -#### Option B: Local Terminal (with SSH key) - -```bash -ssh -i ~/.ssh/id_ed25519 yourusername@ -``` - -#### Option C: VS Code with Remote SSH +## Step 2 - Installing and Finding Your Raspberry Pi +**NOTE:** You can skip ahead to Step 4 while you are waiting for your Raspberry Pi to come in the mail. -1. Install **Remote - SSH** extension in VS Code -2. In the Command Palette: - `Remote-SSH: Connect to Host...` -3. Enter your VM's external IP and SSH key when prompted +There are 3 sections in this step: +1. [Setting up your Raspberry Pi](pi-setup.md) +2. [Using treehouses Remote](treehouses-remote.md) +3. [Finding your Pi](find-pi.md) --- -### 6. Install Required Tools on Your VM - -Connect to the VM and run: - -```bash -sudo apt-get update && sudo apt-get install git unzip -``` - -Then follow Docker’s Debian installation guide here: -https://docs.docker.com/engine/install/debian/#install-using-the-repository +## Step 3 - Use SSH and Tor to Remotely Control Your Raspberry Pi -> You can also reference: -> https://open-learning-exchange.github.io/#!pages/vi/vi-docker-development-tutorial.md +The Systems team uses SSH (Secure Shell) to securely and remotely control the Raspberry Pis we work with. SSH works by providing an admin protocol that allows users to control and modify their remote servers over the Internet. Follow the [Raspberry Pi SSH & Tor Tutorial](sshpi.md) to learn how. --- -### ✅ 7. Node.js and Angular Setup +## Step 4 - Other Services Running from a Raspberry Pi -> ⚠️ Important: **Do not install Node.js as root.** Use your regular user account. - -Install Node.js v14 and Angular CLI v10: - -```bash -curl -fsSL https://deb.nodesource.com/setup_14.x | sudo -E bash - -sudo apt-get install -y nodejs -npm install -g @angular/cli@10 -``` - -Then follow the official tutorial to install and configure the Planet development environment: - -[Planet Docker Development Tutorial](https://open-learning-exchange.github.io/#!pages/vi/vi-docker-development-tutorial.md) - -This includes: - -- Downloading the Planet dev Docker config -- Running CouchDB and ChatAPI services -- Setting up CouchDB with CORS -- Cloning and configuring the `planet` repo +### Nextcloud over Tor -Make sure to complete that guide before moving to the next step. +Follow the [Nextcloud and Tor Tutorial](nextcloud-tor.md) to set up the Nextcloud service on your Pi, and access it via Tor. --- -### 8. Running Planet in the Background - -Start a `screen` session to keep the frontend running after you disconnect: +## Step 5 - Use SSH and Tor to Remotely Control Your Raspberry Pi -```bash -screen -ng serve -``` - -Once the frontend is running, press `Ctrl + A`, then `D` to detach. +The Systems team uses SSH (Secure Shell) to securely and remotely control the Raspberry Pis we work with. SSH works by providing an admin protocol that allows users to control and modify their remote servers over the Internet. Follow the [Raspberry Pi SSH & Tor Tutorial](sshpi.md) to learn how. --- -### 9. Planet Configuration +## Step 6 – Install Planet on Your Local Machine -- When configuring your Planet instance in the browser, choose **Nation** (not Community) -- Avoid common passwords like `12345`, `admin`, etc. +Now that your Raspberry Pi and Google Cloud VM are set up, the final step is to set up Planet on your **local machine** (your laptop or desktop). This gives you a fully networked environment where you can develop, test, and collaborate across all three systems. ---- +Follow the guide below to install Planet using Docker: -### ✅ 10. Share Access +👉 [Planet Docker Development Tutorial](https://open-learning-exchange.github.io/#!pages/vi/vi-docker-development-tutorial.md) -- Send your VM **external IP address** and CouchDB **username/password** to your team -- Your VM is now part of the development network! +Make sure to use the same GitHub credentials across all three systems and configure your local instance to mirror or communicate with the others as needed. If you run into trouble during setup, feel free to ask in the Gitter or Discord support channels. --- -## Step 2 - Installing and Finding Your Raspberry Pi -**NOTE:** You can skip ahead to Step 4 while you are waiting for your Raspberry Pi to come in the mail. - -There are 3 sections in this step: -1. [Setting up your Raspberry Pi](pi-setup.md) -2. [Using treehouses Remote](treehouses-remote.md) -3. [Finding your Pi](find-pi.md) - - -## Step 3 - Use SSH and Tor to Remotely Control Your Raspberry Pi - -The Systems team uses SSH (Secure Shell) to securely and remotely control the Raspberry Pis we work with. SSH works by providing an admin protocol that allows users to control and modify their remote servers over the Internet. Follow the [Raspberry Pi SSH & Tor Tutorial](sshpi.md) to learn how. - - -## Step 4 - System Tutorial - -### Docker - -Docker is a computer program that performs operating-system-level virtualization also known as containerization. In this step, you will learn the basics of interacting with Docker and Docker Compose through the command-line interface and basic commands for maintaining your Planet installation. -Follow the directions in the [Docker Tutorial](dockertutorial.md) - - -## Step 5 - Other Services Running from a Raspberry Pi - -### Nextcloud over Tor - -Follow the [Nextcloud and Tor Tutorial](nextcloud-tor.md) to set up the Nextcloud service on your Pi, and access it via Tor. - - -## Step 6 - Markdown and Fork Tutorial +## Step 7 - Markdown and Fork Tutorial Follow the instructions on [GitHub and Markdown](githubandmarkdown.md) @@ -357,7 +208,7 @@ Make sure that you've linked to your github.io and pull request in the [Discord Check your progress [here](trackprogress.md) -## Step 7 - GitHub Issues Tutorial +## Step 8 - GitHub Issues Tutorial Follow the directions at [Git Repositories](gitrepositories.md) to keep your username.github.io and your local repository up to date. @@ -378,7 +229,7 @@ Check your progress [here](trackprogress.md) Please note that creating and working on Issues are not exactly bound by the "Step" you are in. Feel free to move on to other steps, and make more Issues and Pull Requests while you wait on OLE approval for your merge(s). -## Step 8 - Create Issues and Pull Requests +## Step 9 - Create Issues and Pull Requests In this step, we will adopt the motto of "Practice makes Perfect". You will follow the same steps as in **Step 6**, continuing to improve this Markdown Wiki so that it is educational, yet easy to understand for future interns. @@ -401,7 +252,7 @@ Just as your learning with this Wiki was made possible by the efforts of previou **NOTE**: You can track your progress with the number of pull requests and issues [here](trackprogress.md). -## Step 9 - Be Part of the Team +## Step 10 - Be Part of the Team Next thing is to post a screenshot of your completed progress to the Gitter chat room. Click [here](trackprogress.md) to find your completed progress. Message us ("@/all" and "@dogi") and ask about adding yourself to the virtual intern list found in [team.md](team.md) and setting up a meeting so you can become a part of the team as soon as possible. diff --git a/pages/cloud-vi/vm-setup b/pages/cloud-vi/vm-setup new file mode 100644 index 000000000..61fd7159f --- /dev/null +++ b/pages/cloud-vi/vm-setup @@ -0,0 +1,184 @@ +## Setting up your Google Cloud VM + +This guide will walk you through creating a virtual machine (VM) on Google Cloud Platform (GCP), configuring it securely, and preparing it for Planet development. + +--- + +### 0. Create Google Cloud Account and Billing Setup + +Before we can build a Planet server in the cloud, we’ll need to create a Google Cloud account and configure your virtual machine (VM) environment. + +1. Go to [https://console.cloud.google.com/](https://console.cloud.google.com/) +2. Sign in with your Google account +3. If prompted, create a new Google Cloud project +4. Click the **Billing** tab in the left sidebar +5. Link a valid payment method (credit/debit card) +6. Google may offer a free trial with credits — accept if offered +7. Once your account is active, return to the main console + +### 1. Enable Required APIs + +1. Go to [Google Cloud Console](https://console.cloud.google.com/) +2. In the top search bar, search for **Compute Engine API** +3. Click into it, and click **Enable** +4. Wait for it to activate (this may take a few moments) + +--- + +### 2. Add Your SSH Public Key + +1. Search for **"Metadata"** +2. Click **"Metadata"** under **Compute Engine** +3. Navigate to the **"SSH KEYS"** tab +4. Click **"Edit"**, then **"Add Item"** +5. Paste your full public SSH key, formatted like: + + ``` + ssh-ed25519 AAAAC3... yourusername + ``` + + > You must append a space and your **username** at the end of the key to satisfy Google Cloud’s required format. + > 🔐 Your SSH key should be **password protected** when generated. If you're not sure, re-generate it using: + + ```bash + ssh-keygen -t ed25519 -C "yourusername" + ``` + + and be sure to enter a secure passphrase when prompted. + + +6. Share your key with the team via Discord +--- + +### 3. Create the VM Instance + +1. In the console, go to **Compute Engine > VM Instances** +2. Click **"Create Instance"** +3. Use the following settings: + + - **Name**: `ole-vm` + - **Region**: Select one near you (e.g., `us-east1`) + - **Machine Type**: `e2-medium` (2 vCPU, 4 GB RAM) + - **Boot Disk**: + - Image: `Debian 12 (Bookworm)` + - **Firewall**: + - ✅ Check **Allow HTTP** + - ✅ Check **Allow HTTPS** + +4. Leave all other settings as defaults +5. Click **"Create"** + +> The VM will typically cost $25–$35/month depending on location and usage. + +--- + +### 4. Create Firewall Rule + +1. In the console, search for **"Firewall"** and go to **VPC Network > Firewall** +2. Click **"CREATE FIREWALL RULE"** +3. Set the following: + + - **Name**: `planetdev-rules` + - **Targets**: All instances in the network + - **Source IPv4 Ranges**: `0.0.0.0/0` + - **Protocols and ports**: + - ✅ Check TCP + - Ports: `2200,3000,5000` + +4. Click **"Create"** + +--- + +### 5. SSH Into the VM + +You can SSH into your VM in **three different ways**: + +#### Option A: Google Cloud Console + +- Go to **Compute Engine** +- Click the **SSH** button next to your VM + +#### Option B: Local Terminal (with SSH key) + +```bash +ssh -i ~/.ssh/id_ed25519 yourusername@ +``` + +#### Option C: VS Code with Remote SSH + +1. Install **Remote - SSH** extension in VS Code +2. In the Command Palette: + `Remote-SSH: Connect to Host...` +3. Enter your VM's external IP and SSH key when prompted + +--- + +### 6. Install Required Tools on Your VM + +Connect to the VM and run: + +```bash +sudo apt-get update && sudo apt-get install git unzip +``` + +Then follow Docker’s Debian installation guide here: +https://docs.docker.com/engine/install/debian/#install-using-the-repository + +> You can also reference: +> https://open-learning-exchange.github.io/#!pages/vi/vi-docker-development-tutorial.md + +--- + +### ✅ 7. Node.js and Angular Setup + +> ⚠️ Important: **Do not install Node.js as root.** Use your regular user account. + +Install Node.js v14 and Angular CLI v10: + +```bash +curl -fsSL https://deb.nodesource.com/setup_14.x | sudo -E bash - +sudo apt-get install -y nodejs +npm install -g @angular/cli@10 +``` + +Then follow the official tutorial to install and configure the Planet development environment: + +[Planet Docker Development Tutorial](https://open-learning-exchange.github.io/#!pages/vi/vi-docker-development-tutorial.md) + +This includes: + +- Downloading the Planet dev Docker config +- Running CouchDB and ChatAPI services +- Setting up CouchDB with CORS +- Cloning and configuring the `planet` repo + +Make sure to complete that guide before moving to the next step. + +--- + +### 8. Running Planet in the Background + +Start a `screen` session to keep the frontend running after you disconnect: + +```bash +screen +ng serve +``` + +Once the frontend is running, press `Ctrl + A`, then `D` to detach. + +--- + +### 9. Planet Configuration + +- When configuring your Planet instance in the browser, choose **Nation** (not Community) +- Avoid common passwords like `12345`, `admin`, etc. + +--- + +### ✅ 10. Share Access + +- Send your VM **external IP address** and CouchDB **username/password** to your team +- Your VM is now part of the development network! + +--- \ No newline at end of file From 352f4a5100a42cae2ba51a5552137b638ab0dc80 Mon Sep 17 00:00:00 2001 From: Jesse Washburn <142361664+jessewashburn@users.noreply.github.com> Date: Fri, 13 Jun 2025 14:27:39 -0400 Subject: [PATCH 06/10] fixed link to vm-setup --- pages/cloud-vi/firststeps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cloud-vi/firststeps.md b/pages/cloud-vi/firststeps.md index d4d11cc4e..1de795db1 100644 --- a/pages/cloud-vi/firststeps.md +++ b/pages/cloud-vi/firststeps.md @@ -144,7 +144,7 @@ VS Code offers a user-friendly and powerful coding environment. To begin, you’ll set up a Debian-based virtual machine on Google Cloud. This VM will serve as your cloud-hosted Planet node and is a key part of the networked development environment. Follow the full setup instructions here: -👉 [pages/cloud-vi/vm-setup.md](pages/cloud-vi/vm-setup.md) +👉 [vm-setup](vm-setup) Once complete, you’ll have a persistent, internet-accessible system ready to run Docker containers, host Planet, and connect with your Raspberry Pi and local machine. From fb3d379a702952c4b31add11f1d1a14fc10daeea Mon Sep 17 00:00:00 2001 From: Jesse Washburn <142361664+jessewashburn@users.noreply.github.com> Date: Fri, 13 Jun 2025 14:41:28 -0400 Subject: [PATCH 07/10] filetype fix --- pages/cloud-vi/{vm-setup => vm-setup.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename pages/cloud-vi/{vm-setup => vm-setup.md} (100%) diff --git a/pages/cloud-vi/vm-setup b/pages/cloud-vi/vm-setup.md similarity index 100% rename from pages/cloud-vi/vm-setup rename to pages/cloud-vi/vm-setup.md From 6bd7cbebf1b920d0de22da39a29126a56982027b Mon Sep 17 00:00:00 2001 From: Jesse Washburn <142361664+jessewashburn@users.noreply.github.com> Date: Fri, 13 Jun 2025 14:47:55 -0400 Subject: [PATCH 08/10] filetype --- pages/cloud-vi/firststeps.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/cloud-vi/firststeps.md b/pages/cloud-vi/firststeps.md index 1de795db1..f0df83c9d 100644 --- a/pages/cloud-vi/firststeps.md +++ b/pages/cloud-vi/firststeps.md @@ -144,7 +144,7 @@ VS Code offers a user-friendly and powerful coding environment. To begin, you’ll set up a Debian-based virtual machine on Google Cloud. This VM will serve as your cloud-hosted Planet node and is a key part of the networked development environment. Follow the full setup instructions here: -👉 [vm-setup](vm-setup) +👉 [vm-setup](vm-setup.md) Once complete, you’ll have a persistent, internet-accessible system ready to run Docker containers, host Planet, and connect with your Raspberry Pi and local machine. From 724a27b19957d16b522695baf5632a47845dbfd2 Mon Sep 17 00:00:00 2001 From: Jesse Washburn <142361664+jessewashburn@users.noreply.github.com> Date: Fri, 13 Jun 2025 15:24:43 -0400 Subject: [PATCH 09/10] formatting cleanup --- pages/cloud-vi/vm-setup.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/pages/cloud-vi/vm-setup.md b/pages/cloud-vi/vm-setup.md index 61fd7159f..33b5105bd 100644 --- a/pages/cloud-vi/vm-setup.md +++ b/pages/cloud-vi/vm-setup.md @@ -33,12 +33,10 @@ Before we can build a Planet server in the cloud, we’ll need to create a Googl 4. Click **"Edit"**, then **"Add Item"** 5. Paste your full public SSH key, formatted like: - ``` - ssh-ed25519 AAAAC3... yourusername - ``` + `ssh-ed25519 AAAAC3... yourusername` - > You must append a space and your **username** at the end of the key to satisfy Google Cloud’s required format. - > 🔐 Your SSH key should be **password protected** when generated. If you're not sure, re-generate it using: +> You must append a space and your **username** at the end of the key to satisfy Google Cloud’s required format. +> Your SSH key should be **password protected** when generated. If you're not sure, re-generate it using: ```bash ssh-keygen -t ed25519 -C "yourusername" From 73cd597c75575c88ebe70616be2f5856f6a9cba9 Mon Sep 17 00:00:00 2001 From: Jesse Washburn <142361664+jessewashburn@users.noreply.github.com> Date: Fri, 20 Jun 2025 14:49:39 -0400 Subject: [PATCH 10/10] folder renamed --- index.md | 2 +- pages/{cloud-vi => ci}/firststeps.md | 0 pages/{cloud-vi => ci}/vm-setup.md | 0 3 files changed, 1 insertion(+), 1 deletion(-) rename pages/{cloud-vi => ci}/firststeps.md (100%) rename pages/{cloud-vi => ci}/vm-setup.md (100%) diff --git a/index.md b/index.md index 5342e7f26..7c6934fdc 100644 --- a/index.md +++ b/index.md @@ -19,6 +19,6 @@ Should you wish to reach out for information or assistance, feel free to contact #### Become a Virtual Intern! Follow these first steps: For hardware-based systems engineering: [first steps](pages/vi/firststeps.md). -For cloud-based systems engineering: [first steps](pages/cloud-vi/firststeps.md). +For cloud-based systems engineering: [first steps](pages/ci/firststeps.md). **Find Us On:** [Linkedin](https://www.linkedin.com/company/open-learning-exchange) | [Twitter](https://twitter.com/oleorg) | [Facebook](https://www.facebook.com/openlearningexchange/) diff --git a/pages/cloud-vi/firststeps.md b/pages/ci/firststeps.md similarity index 100% rename from pages/cloud-vi/firststeps.md rename to pages/ci/firststeps.md diff --git a/pages/cloud-vi/vm-setup.md b/pages/ci/vm-setup.md similarity index 100% rename from pages/cloud-vi/vm-setup.md rename to pages/ci/vm-setup.md