Getting Started on worms.sh

This is a guide for getting an account set up on worms.sh and logging in your first time. Since worms.sh is a basic UNIX-like¹ server with 1 CPU core and 1 GB RAM, there’s no graphical interface, just a simple text terminal! If this is your first time using a terminal, don’t worry – you’ll learn quickly and feel comfortable in no time.

If you have questions, check the Companion FAQ!

Note: this guide only has instructions for Mac and is limited in its scope -- for a more comprehensive guide, including instructions for Windows, check out this guide!

Mac

Since MacOS is a UNIX-like OS, getting set up is relatively straightforward.

You’ll need access to the Terminal application. You can find it by searching for it in Spotlight (Cmd-Space) or looking in your Applications folder. It may be in a ‘Utilities’ sub-folder.

Command line shell basics

Before getting into how to access worms.sh, I’ll go over some command line basics. If you want a more thorough introduction, this one from Ubuntu Linux is pretty good. A couple details won’t apply on your Mac (or on worms.sh), but the basics are the same.

Open up your Terminal app. You should see something like:

baba@macbook ~ %

This is an interactive command line shell! The primary purpose of a UNIX shell is to take program names as input and run those commands. For example, try typing ls and press Enter. You should see a list of familiar names appear on the screen. You just ran the ls program, which lists the files and directories in your current directory!² To find out what your current directory is, try running the pwd program:

baba@macbook ~ % pwd
/Users/baba

pwd is short for “Parent Working Directory”, and the program prints the directory you are currently in. You should see that you’re currently in your user’s home directory, explaining why ls showed you the files in your home directory.

cd is another useful program which stands for “Change Directory.” Try running cd Documents and then running the pwd and ls commands. You can navigate to virtually any directory on your computer with cd and check out its contents with ls.

The UNIX shell can run all sorts of programs, including file management programs, text editors, data processing programs, and more. Anything that a computer can do that doesn’t inherently depend on graphics can be done through the command line interface!

The UNIX shell is a powerful tool and will be the primary way that you interact with worms.sh. While there’s a lot more to the UNIX shell and many programs to learn about, we’ll stop here and get you set up on worms.sh. Once you’re logged onto worms.sh, you can explore freely without worrying about messing up any important files on your computer!

Setting up your credentials

You’ll use ssh to access your interactive shell on worms.sh. SSH is the most widely used protocol for securely accessing remote shells and is already installed on your Mac! To authenticate with worms.sh, you need to create an SSH key pair. You can read up on the technical details if you’re interested, but you don’t need to know the details to set it up. The basic idea is that you’ll generate a random key which will allow you to authenticate with the worms.sh server. This key will live on your computer, meaning you can only log in to your account using the computer you generate the key with! If you have multiple computers, you can repeat the process with each to add a key from each computer.

To generate an SSH key, follow these steps (if at any point you make a mistake, you can type Ctrl-C to terminate the command):

1. Open a new Terminal window.
2. Run the following command: ssh-keygen -t ed25519
3. You will be guided through an interactive process. For the first prompt, press Enter to accept the default key file.³ It should be something like /Users/<username>/.ssh/id_ed25519.
4. For the next prompt, enter a passphrase for the key. Please choose a secure passphrase! While you’re allowed to make a key without a passphrase, this lowers the security considerably. Note that when you type, you won’t see any characters appear on screen. Don’t worry, your inputs are still registering!
5. You’ll be asked to confirm the passphrase
6. If successful, you’ll see a message telling you where your identifications and public key are saved, along with a “key fingerprint” and a randomart image. You now have an SSH key!

In actuality, your SSH key is two keys. It consists of a private key (id_ed25519) and a public key (id_ed25519.pub). As the names suggest, your private key is secret and your public key is public!⁴ You can share your public key as widely as you please. In fact, you’ll need to share it with me, the administrator, in order for me to grant you access to worms.sh. However, you should take great care to keep your private key secret!

To view your public key, type the following command: cat ~/.ssh/id_ed25519.pub. Here’s my public key as an example:

baba@macbook ~ % cat ~/.ssh/id_ed25519.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGV6m2CcaZXez2AesDqBETIJJzigsE4Vtv/StBo+q/oe baba@macbook

Once you generate your public key, you’ll need to send it to the admin along with your username! Once this is done, you can continue below to Connecting to worms.sh.

Connecting to worms.sh

At this point, you should have an SSH key pair generated and confirmation from baba that your account is set up with your SSH public key authorized. Logging in is simple:

baba@macbook ~ % ssh admin@worms.sh
Enter passphrase for key '/Users/baba/.ssh/id_ed25519':
Last login: Sat Aug 3 05:48:28 2024 from tmux(64826).%4
FreeBSD 14.1-RELEASE (GENERIC) releng/14.1-n267679-10e31f0946d8

Welcome to worms.sh!

This system runs FreeBSD 14.1.

If you have questions, break anything, or have suggestions, don't hesitate to
reach out! We're all here to learn together :)
admin@earth /home/admin
>

In this example, I am logging in as user admin; you’ll use the username you chose, i.e. ssh <your-username>@worms.sh. Once logged in, you’ll be dropped into an interactive shell, just like the one on your Mac – except now you’re remotely interacting with the worms.sh server!⁵

You can now run the commands you were running before, like ls. If you run ls, you’ll see just one file – a directory called public_html. Try running cd public_html and then ls again. This time, you’ll see a file called index.html. This is your homepage which is hosted on worms.sh/~<your-username>! Now we’ll go over how to edit this file.

Editing text

To edit your homepage, you’ll need to use a text editor. FreeBSD has a simple built-in editor called ee. Try running ee from your interactive prompt; the text in your terminal should clear and be replaced by the text editor interface. At the top will be a few lines of text like this:

^[ (escape) menu ^y search prompt ^k delete line   ^p prev li     ^g prev page
^o ascii code    ^x search        ^l undelete line ^n next li     ^v next page
^u end of file   ^a begin of line ^w delete word   ^b back 1 char ^z next word
^t top of text   ^e end of line   ^r restore word  ^f forward char
^c command       ^d delete char   ^j undelete char              ESC-Enter: exit
=====line 1 col 0 lines from top 1 ============================================

These are the available shortcuts in ee, where ^ is Ctrl. If you start typing text, you should see it appear under this menu. When you run ee, you’ll start editing a new file. Since we want to edit index.html, let’s exit out and start over – press ESC-Enter and then select the b) no save option with Enter. You’ll be dropped back into your shell in the directory you were in.

In addition to running programs, the command line shell can also pass “arguments” to those programs. Arguments are ways of giving the program additional inputs such as file names, input text, or enabling optional features (“options”). Each program has different allowed inputs and options; thankfully, you can always read up on how to use a program by reading its manual with the man program. Try running man ee. You should see a document like this:

ee(1) ee(1)

            NAME
            ee - easy editor

            SYNOPSIS
            ee [-e] [-i] [-h] [+#] [file ...]
            ree [-e] [-i] [-h] [+#] [file ...]
            [...] 

You can scroll through with your arrow keys (mouse scrolling might work too). You don’t really need to know the details about ee, but the synopsis gives us useful information. Here, we see the allowed methods of running ee. The square brackets indicate optional arguments – since they’re all optional, you can run ee on its own, like we did just earlier! But we can also provide one or more files [file ...]. Let’s try it – press q to quick out of the manual program and get back to your shell.⁶

Now, make sure you’re in the public_html directory, where index.html lives. If you’re not, use cd to navigate to ~/public_html (~ is shorthand for your home directory in file paths). Then, run ee again, but this time give index.html as an argument: ee index.html. You should see some HTML code, which you can now start editing! You can save your work by opening the main menu with ESC and navigating to the file operations submenu, where you’ll see a save option. ee supports Emacs-style keybindings – this is a way of saying you can string a series of key presses together to specify certain commands without manually navigating each menu. For instance, you can save by pressing ESC c c, one key press after the other.

As soon as you edit index.html and save, you can refresh your browser and see the updated changes at worms.sh/~<your-username>!

Finally, to navigate back to your home directory, you can do cd ... The .. is a shorthand for the parent directory to the one you’re currently in.

Conclusion

Congratulations! You now have all the tools you need to start editing your home page and exploring the FreeBSD operating system on worms.sh! It might seem intimidating and cumbersome at first, but it’ll all become second nature as you grow accustomed to working through a terminal interface.

A couple final notes. 1. Please don’t be afraid to ask questions! We’re all here to learn together. 2. Don’t be afraid to experiment! Try things, write scripts and programs, write web pages that bring down the whole server – the more you break things, the more I get to learn as an administrator :)

Notes, next steps, useful programs, tidbits, etc…

Next steps?

We went through a few basic UNIX shell commands, but we barely scratched the surface. You don’t even know how to make a new directory, rename a file, or delete stuff! This article gives a pretty good overview of core UNIX commands. The first two sections are the most important. Here’s what I would consider the minimal list of commands to know: cd, ls, pwd, mkdir, rmdir, cp, mv, rm, cat, less, and man. You can probably guess what most of these do (except for cat…) just by their names. If you know these by heart and have a text editor handy, you can do basically anything!

A word of caution: be very careful when using commands like cp, mv, and especially rm. All of these can and will irrevocably delete or overwrite files without asking for confirmation. Always double check that these commands will do what you want them to do, and don’t run commands or use options you don’t understand! On that note, also keep in mind that this server is not backed up. Keep a copy of important data (like your webpage!!) somewhere else.

Cool programs

There’s a range of terminal-based editors out there if you want to improve your editing workflow (my favorite is vim/neovim). You can also edit on your computer and push changes in via a number of methods, like scp or by creating a remote git repository. This website itself (and the entire server infrastructure, eventually) is kept in a git repository at github.com/worms-sh/worms.sh!

tmux is a tool I’ve been using daily for years now (including now, as I write this). You probably don’t need it right away, but if you ever find yourself spending more than a few minutes at a time in the shell, you’ll find it handy.

Your shell is configurable. By default, you’ll be dropped into a zsh shell when you log in. Unless you have a reason to, you probably shouldn’t change this. You can configure zsh by editing configuration files in your home directory such as ~/.zshrc. You probably don’t have one now; to look at mine, try running cat /home/baba/.zshrc.

Side note: files that start with a . character (like ~/.zshrc) are hidden. You can see them by using the -a option in ls: ls -a. If you run that in your home directory, you’ll probably see a few hidden files already. Many of these are used for configuring programs.

Resources

This guide from a college webdev course's pubnix server is super helpful! It has a more comprehensive introduction to the terminal. The course website is also very cool! I learned some formatting tricks from just reading the page source.

W3C has an HTML tutorial that I’ve been following. MDN [has guides as well][mdn] and seems like the go-to online web dev reference. They also both have tutorials for CSS and JavaScript, which are technologies you’ll probably want to use. There are tools out there which can make editing your web page easier – this page was written in Markdown and translated into html using pandoc, which is a great for simple pages like this. There are a million web frameworks out there and I’d be happy to help you set any of them up! Here’s some relevant terminology I’ve found to aid your research: static site generator (SSG), template engine, CSS framework, JS framework.

git is an extremely useful tool to track and distribute changes to your code. The git website has a good guide to getting started, although it’s a bit tedious to go through the whole thing. Section 1.6 will get you set up and Chapter 2 goes through the basics. You’ll need to host a remote git repository somewhere; GitHub is the most popular and is easy to use, but alternatives are aplenty. Codeberg is a non-commercial alternative, if that floats your boat.

Remember to read man pages before you run new commands! They’re intimidating, but they contain a wealth of information, and reading just the Synopsis and the Description sections will go a long way. Additionally, the FreeBSD Handbook is the go-to reference for anything system-related. You probably don’t need this (it’s more for me than for you), but if you want to gain a deeper appreciation of how the system works, Chapter 3 of the Handbook is a good place to start.

Lmk if you have suggestions for additional resources or any feedback on this guide!