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 Nest Bot application]]
Before you are able to create an account, you must enroll. On the [https://hackclub.com/slack Hack Club Slack], open the Nest Bot app by searching "Nest Bot" in the search bar, and clicking on the Nest Bot app. Then, click "Register yourself!"
* 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.
'''Warning:''' Your username cannot start with a number. Also, don't pick something like "admin" or "login" as a username.
* 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:
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! 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:
cat ~/.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, Nest Bot will tell you that your request is under review. Once you are approved, Nest Bot will let you know, and give you your password. This is the password that you'll use to access Nest services through [[Authentik]]. 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!
username@hostname:~$
bash-3.2$
PS C:\Users\username>
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.
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.
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:
=== Using the Account ===
Now you will have to log in over [[SSH]]. From your terminal, run
$ ssh <username>@hackclub.app
Replace <username> with your username. You should see an ASCII art NEST and the Hack Club dinosaur.
~$ echo "Hello, world!"
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.
and press 'Enter', your terminal will read:
==== 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
~$ echo "Hello, world!"
==== Git ====
Hello, world!
If you have your website on GitHub or GitLab, you can clone it.
~$
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
The echo command 'echoes' whatever is after it:
==== Uploading Files Over SCP ====
If you have a website locally, you can upload it to your server. On your local device, run
[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!
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.
You can then run on the pub
$ unzip [zip file]
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.
to unzip your folder!
Other linux commands that are useful to know include:
* <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 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
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__
Latest revision as of 17:13, 27 March 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
The Home tab on the Nest Bot application
Before you are able to create an account, you must enroll. On the Hack Club Slack, open the Nest Bot app by searching "Nest Bot" in the search bar, and clicking on the Nest Bot 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! 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:
cat ~/.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, Nest Bot will tell you that your request is under review. Once you are approved, Nest Bot will let you know, and give you your password. This is the password that you'll use to access Nest services through Authentik. 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 username. You should see an ASCII art NEST and the Hack Club dinosaur.
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.
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
