Quickstart: Difference between revisions

Latest revision as of 03:58, 30 October 2024

Welcome to Nest!

This guide will walk you through creating an account and setting up a Caddy webpage. It assumes basic knowledge about the terminal—read up on that on Linux if you're unsure! Also, please review the Acceptable Use Policy before getting started with Nest.

Creating an Account

Before you are able to create an account, you must verify that you are a student. Please see verifying your student status for more details. You cannot proceed with the following steps without doing this.

Now, on the Hack Club Slack, open the Quetzal (Nest's mascot) app by searching "Quetzal" in the search bar, and clicking on the Quetzal app. Then, click "Register yourself!"

Warning: Your username cannot start with a number. Also, don't pick something like "admin" or "login" as a username.

The signup flow will need some basic information—namely, your username, name, email address, and SSH key, which is how you will log into the Nest server. If you don't have an SSH key, no worries - you can make one now!

On ChromeOS? You'll have to use ChromeOS' built-in Linux integration. Go to Settings, search "Linux", and follow the instructions to get it setup if you haven't already. Once you're done, open up the Linux terminal.

Simply open up your terminal (such as Windows Powershell or the Terminal app on MacOS), and type:

ssh-keygen -t rsa

Answer the prompts (you can accept defaults by pressing Enter), and it will generate a key for you. To get it, type this on MacOS/Linux:

cat ~/.ssh/id_rsa.pub

or this on Windows (replacing username with the name of your user on Windows):

type C:\Users\username\.ssh\id_rsa.pub

Copy the value that this outputs, and paste it into the "Public SSH Key" field of the Nest signup form.

Once you've completed the signup flow, Quetzal will tell you that your request is under review. Once you are approved, Quetzal will let you know, and give you your password. This is the password that you'll use to access Nest services through Authentik. It's a good idea to change this password - go ahead and login to Authentik at https://identity.hackclub.app and change your password by clicking on the settings gear in the top-right corner, and then clicking the "Change password" button. Change it to something secure!

You can also link your Authentik account to your Slack account, if you wish. This will let you login to Authentik through your Slack account. To do this, simply go to the "Connected services" tab of the same settings page, and click the "Connect" button next to the Slack icon.

Using the Account

Now you will have to log in over SSH. From your terminal, run

  $ ssh <username>@hackclub.app

Replace <username> with your Nest username. You should see "Welcome to Nest!". If you see something like "Permission denied" instead, make sure you've spelled your Nest username correctly and have the SSH key that you used to sign up for Nest on your computer.

Your website is in ~/pub/, your Caddyfile (server configuration) in ~/Caddyfile, and your website accessible at <username>.hackclub.app. From here, you have multiple options to set up your website - Caddy will automatically serve whatever you put in ~/pub/! If you'd like to learn more about Caddy and what it can do, check out the Caddy page.

The Lazy Way™

You are able to write your website straight from the terminal using your editor of choice.

  username@nest:~$ nano ~/pub/index.html

Git

If you have your website on GitHub or GitLab, you can clone it after deleting the default index.html file:

username@nest:~$ rm ~/pub/index.html
username@nest:~$ git clone <git repo url> ~/pub/

You can setup a cronjob to pull changes daily if you don't want to pull manually.

  username@nest:~$ crontab -e
  0 0 * * * cd ~/pub && git pull origin main 2>~/git-error

Uploading Files Over SCP

If you have a website locally, you can upload it to your server. On your local device, run

  $ tar cvf website.tar /path/to/website
  $ scp website.tar <username>@hackclub.app:/home/<username>/pub

Then over SSH, navigate to pub and use

  username@nest:~/pub$ tar xvf website.tar

Uploading Files Over Croc

Croc is a fast & simple tool for uploading files to remote machines. Install it on your local machine, zip up your files, and run

  $ croc [zip file]

Then over SSH, navigate to pub and run

  $ croc [recieve-code-from-local-machine]

to download the zip!

You can then run on the pub

 $ unzip [zip file]

to unzip your folder!

Not a website? No problem!

Since Nest is just a normal Linux server, you can host pretty much anything on it, from Slack/Discord bots to complex full-stack apps. See Caddy for how to reverse proxy (forward) your subdomain to your app, and Systemd for how to keep it running!

@@ Line 1: / Line 1: @@
 == Welcome to Nest! ==
-This quickstart guide walks you through creating an account, logging in, and creating a simple static webpage using Caddy.
+__NOEDITSECTION__
-== Basic Usage ==
+This guide will walk you through creating an account and setting up a [[Caddy]] webpage. It assumes basic knowledge about the terminal—read up on that on [[Linux]] if you're unsure! Also, please review the [[Acceptable Use Policy]] before getting started with Nest.
-=== Using the Terminal ===
+=== Creating an Account ===
-Most modern operating systems will ship with a terminal. A terminal allows you to run commands that will tell your computer what to do. You will be using the terminal for most of this guide.
+[[File:Nest Home Tab.png|thumb|The Home tab on the Quetzal application]]
+Before you are able to create an account, you must verify that you are a student. Please see [[verifying your student status]] for more details. You '''cannot''' proceed with the following steps without doing this.
-* On windows, the default terminal is either cmd.exe or PowerShell. You have the option of using these, or using WSL or PuTTY to connect to Nest.
+Now, on the [https://hackclub.com/slack Hack Club Slack], open the Quetzal (Nest's mascot) app by searching "Quetzal" in the search bar, and clicking on the Quetzal app. Then, click "Register yourself!"
-* On macOS, the default terminal is Terminal. There are also other Terminal apps you can install for free, such as AlacriTTY or iTerm2.
-* On Linux, the default terminal application will vary, but is usually titled Terminal or Console.
-Once you have selected a terminal, you will be greeted with a prompt similar to one of these upon opening the terminal:
+'''Warning:''' Your username cannot start with a number. Also, don't pick something like "admin" or "login" as a username.
-  ~$
+The signup flow will need some basic information—namely, your username, name, email address, and [[SSH]] key, which is how you will log into the Nest server. If you don't have an SSH key, no worries - you can make one now!<blockquote>On ChromeOS? You'll have to use ChromeOS' built-in Linux integration. Go to Settings, search "Linux", and follow the instructions to get it setup if you haven't already. Once you're done, open up the Linux terminal.</blockquote>Simply open up your terminal (such as Windows Powershell or the Terminal app on MacOS), and type:
- username@hostname:~$
+  ssh-keygen -t rsa
-  bash-3.2$
+Answer the prompts (you can accept defaults by pressing Enter), and it will generate a key for you. To get it, type this on MacOS/Linux:
-  PS C:\Users\username>
+  cat ~/.ssh/id_rsa.pub
+or this on Windows (replacing username with the name of your user on Windows):
+  type C:\Users\username\.ssh\id_rsa.pub
+Copy the value that this outputs, and paste it into the "Public SSH Key" field of the Nest signup form.
-For the rest of this guide, we will be using the first, but don't be alarmed if yours looks different. In addition, we will be focused on Linux commands, since that is what Nest runs on. The concept applies to Windows as well, however some commands are different.
+Once you've completed the signup flow, Quetzal will tell you that your request is under review. Once you are approved, Quetzal will let you know, and give you your password. This is the password that you'll use to access Nest services through [[Authentik]]. It's a good idea to change this password - go ahead and login to Authentik at https://identity.hackclub.app and change your password by clicking on the settings gear in the top-right corner, and then clicking the "Change password" button. Change it to something secure!
-To run a command, simply type your command and press the 'Enter' or 'Return' key. Once you do, the output of the command will be displayed right below the prompt. For example, if you type:
+You can also link your Authentik account to your Slack account, if you wish. This will let you login to Authentik through your Slack account. To do this, simply go to the "Connected services" tab of the same settings page, and click the "Connect" button next to the Slack icon.
- ~$ echo "Hello, world!"
+=== Using the Account ===
+Now you will have to log in over [[SSH]]. From your terminal, run
+   $ ssh <username>@hackclub.app
+Replace <username> with your Nest username. You should see "Welcome to Nest!". If you see something like "Permission denied" instead, make sure you've spelled your Nest username correctly and have the SSH key that you used to sign up for Nest on your computer.
-and press 'Enter', your terminal will read:
+Your website is in <code>~/pub/</code>, your [[Caddy#Caddyfile|Caddyfile]] (server configuration) in <code>~/Caddyfile</code>, and your website accessible at <code><username>.hackclub.app</code>. From here, you have multiple options to set up your website - Caddy will automatically serve whatever you put in <code>~/pub/</code>! If you'd like to learn more about Caddy and what it can do, check out the [[Caddy]] page.
- ~$ echo "Hello, world!"
+==== The Lazy Way™ ====
- Hello, world!
+You are able to write your website straight from the terminal using your editor of choice.
- ~$
+   username@nest:~$ nano ~/pub/index.html
-The echo command 'echoes' whatever is after it:
+==== Git ====
+If you have your website on GitHub or GitLab, you can clone it after deleting the default index.html file:
+ username@nest:~$ rm ~/pub/index.html
+ username@nest:~$ git clone <git repo url> ~/pub/
+You can setup a cronjob to pull changes daily if you don't want to pull manually.
+   username@nest:~$ crontab -e
+0 * * * cd ~/pub && git pull origin main 2>~/git-error
- ~$ echo "I am creating a website using Nest!"
+==== Uploading Files Over SCP ====
- I am creating a website using Nest!
+If you have a website locally, you can upload it to your server. On your local device, run
- ~$
+   $ tar cvf website.tar /path/to/website
+   $ scp website.tar <username>@hackclub.app:/home/<username>/pub
+Then over SSH, navigate to pub and use
+   username@nest:~/pub$ tar xvf website.tar
-Commands are usually of the format <code>command options arguments</code>. Options are usually prefixed with one or two dashes (ie, <code>-o --option</code>). One dash signifies an option that is one letter long, and allows you to chain options (ie, <code>-al</code> is the same as <code>-a -l</code>). Two dashes signify a single option which is usually an entire word or phrase (ie, <code>--output</code>). It is important to note that all commands follow these rules, and not all commands have the same options. You can usually check a command's manual page using <code>man command</code> to get a list of options, or run the command with <code>-h</code> or <code>--help</code> to get information about the command.
+==== Uploading Files Over Croc ====
+[https://schollz.com/tinker/croc6/ Croc] is a fast & simple tool for uploading files to remote machines. Install it on your local machine, zip up your files, and run
+   $ croc [zip file]
+Then over SSH, navigate to pub and run
+   $ croc [recieve-code-from-local-machine]
+to download the zip!
-Notice how the <code>~$</code> is repeated at the end. Whenever you see the <code>~$</code> (or your computer's equivalent), it means that your terminal is ready for another command.
+You can then run on the pub
+  $ unzip [zip file]
+to unzip your folder!
-Other linux commands that are useful to know include:
+==== Not a website? No problem! ====
+Since Nest is just a normal Linux server, you can host pretty much anything on it, from Slack/Discord bots to complex full-stack apps. See [[Caddy#Reverse Proxy|Caddy]] for how to reverse proxy (forward) your subdomain to your app, and [[Systemd]] for how to keep it running!
-* <code>cd</code>, <strong>C</strong>hange <strong>D</strong>irectory - Notice the tilde (~) or path (C:\Users\username) in the examples above? That is known as your current working directory, or CWD. It corresponds to the folder that your terminal is in, and will affect what certain commands do. Using <code>cd</code>, you can change your working directory:
- ~$ cd Documents
- ~/Documents$
-Folders can be nested inside other folders, indicated with a slash (/). On windows, a backslash (\) is used instead. the tilde (~) corresponds to your home directory, which is /Users/username on macOS and /home/username on Linux.
-* <code>ls</code>, <strong>L</strong>i<strong>s</strong>t - This command will list what files and folders exist in the CWD or path provided:
- ~$ ls
- Desktop  Documents  Downloads
- ~$ ls Documents
- Contract.pdf  Taxes  Work
-Adding <code>-l</code> expands the list and provides more information:
- ~$ ls -al
- drwxr-xr-x 2 username username 4096 Dec 17 06:43 Desktop
- drwxr-xr-x 2 username username 4096 Dec 18 22:22 Documents
- drwxr-xr-x 2 username username 4096 Nov 12 15:08 Downloads
- ~$ ls -al Documents
- -rw-r--r-- 1 username username  524288 Dec 18 22:22 Contract.pdf
- drwxr-xr-x 2 username username    4096 Apr 21 07:32 Taxes
- drwxr-xr-x 2 username username    4096 Dec 18 15:43 Work
-For information on how to read the output, see [[Linux]].
-* <code>mkdir</code> - this command creates a new directory.
-* <code>cat</code> - This command reads the contents of a file
-* <code>nano</code>, <code>vi</code> - These are text editors. <code>nano</code> is recommended for beginners due to its ease of use.
-=== Creating an SSH key ===
-In order to connect to Nest, you will need to generate an [[SSH]] key:
- ~$ ssh-keygen
-This should walk you through the process of creating an SSH key. It will first ask you where to save the key:
- ~$ ssh-keygen
- Generating public/private rsa key pair.
- Enter file in which to save the key (/home/username/.ssh/id_rsa):
-Just hit enter to default to <code>/home/username/.ssh/id_rsa</code>. It will then ask for a passphrase to protect the key, and again to confirm. Make sure to write this down or keep it in a password vault, as if you forget this passphrase you will be unable to connect to Nest.
- ~$ ssh-keygen
- Generating public/private rsa key pair.
- Enter file in which to save the key (/home/username/.ssh/id_rsa):
- Created directory '/home/username/.ssh'.
- Enter passphrase (empty for no passphrase):
- Enter same passphrase again:
-As you type the passphrase, nothing will appear on screen to ensure that nobody can see your passphrase. Once you confirm the passphrase, <code>ssh-keygen</code> will generate your ssh key:
- ~$ ssh-keygen
- Generating public/private rsa key pair.
- Enter file in which to save the key (/home/username/.ssh/id_rsa):
- Created directory '/home/username/.ssh'.
- Enter passphrase (empty for no passphrase):
- Enter same passphrase again:
- Your identification has been saved in /home/username/.ssh/id_rsa
- Your public key has been saved in /home/username/.ssh/id_rsa.pub
- The key fingerprint is:
- SHA256:z+5EMjn7MNxA52sLavZZt0RTrSKT2inH5Yr4LIxp54I aurora@nest
- The key's randomart image is:
- +---[RSA 3072]----+
- |                 |
- |               . |
- |        . .   . .|
- |       . + . . . |
- |        S * = .  |
- |       . # O o   |
- |   . +  O & +    |
- |  E = *+ # = .   |
- |   . *++*.* .    |
- +----[SHA256]-----+
-You will then need your public key. Use <code>cat</code> to read the public key. By default it is located in <code>/home/username/.ssh/id_rsa.pub</code>:
- ~$ cat /home/username/.ssh/id_rsa.pub
- ssh-rsa AAAA...o4Nc= username@hostname
-The line beginning with <code>ssh-rsa</code> is your public key. You will want to copy this. If you get an output like this:
- ~$ cat /home/username/.ssh/id_rsa
- -----BEGIN OPENSSH PRIVATE KEY-----
- b3Bl...
- ...
- ...
- ...c3Q=
- -----END OPENSSH PRIVATE KEY-----
-That is your private key. Do not share that with anyone, or they will have access to your Nest user. It is best to not touch the <code>.ssh/id_rsa</code> file unless you know what you are doing. On the other hand, you will need to share your public key to gain access to Nest.
-=== Signing Up ===
-<!-- TODO: Fill in once sign up flow is complete -->
-=== Logging In ===
-Authentication is handled by [[Authentik]]. Once your account is created, visit the Nest [https://identity.hackclub.app/ Authentik Instance] to log in with your username and password.
-[[File:Nest Authentik Homepage.png|thumb|The homepage of Authentik. Clicking on any link under My Applications will redirect you to that application.]]
-Once logged in, you can log into any Nest service which supports Authentik, such as this MediaWiki instance, using 'Sign in with Nest'.
-You can also navigate to any application which supports Sign in with Nest from the Authentik main page by clicking on one.
-=== Connecting over SSH ===
-You can connect to Nest using [[SSH]]. This will open a new terminal that is running on Nest.
- ~$ ssh yourusername@hackclub.app
-                                           .MM.
-                                           ;MM.
- KKc.lONMMWXk;    ckXWMMWXk:   'xXWMMWXxoKKNMMXKKKK
- MMXNo'.  .lWM0.oWNo'.  .,dWWldMW:.  .:XMN'dMM:....
- MMW.       :MMWMN.        'MMMMWc.     .. cMM.
- MMO        .MMMMWXXXXXXXXXXWWO,dKNMNKOd:. cMM.
- MMO        .MMMMX                  .':OMMccMM.
- MMO        .MMKNMO.      .kK0KKl      .MMk:MM;
- MMO        .MMd.oXMKxoox0MXl ,OMNkdodkWWk. kWMKOOo
- dd:        .dd;   ,xKNNKx,     .o0XNX0l.    .:oddc
-  ___________________________________
- / Welcome to nest!                  \
- |                                   |
- \ docs: https://guides.hackclub.app /
-  -----------------------------------
-           \
-            \
-             \  __
-               / _)
-      _.----._/ /
-     /         /
-  __/ (| | (  |
- /__.-'|_|--|_|
- Last login: Mon Dec 18 21:42:28 2023 from 76.102.2.149
- username@nest:~$
-Once you see this, you have connected to Nest. You are now ready to begin deploying your first webpage!
-=== Using Caddy ===
-<!--TODO: write this-->
- __NOEDITSECTION__