💾 Archived View for tilde.team › ~smokey › logs › 2021-12-01-gemsdf.gmi captured on 2023-11-14 at 08:19:53. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2022-06-11)
-=-=-=-=-=-=-
Today I am going to teach you how to create and maintain a gemini capsule through sdf.org. I write this beginner friendly guide with the intent to be streamlined and simple to understand. The goal is giving you clear instructions to make the process as painless as possible. Hopefully get your first gemini capsule up and running, and provide valuable information not easy accessable through the SDF wiki gemini page (at least when i tried finding it). First, I would like to clarify some terms and explain what we will be doing in case someone completely new to gemini and servers stumbles across this.
SDF is a a non-profit organization that maintains a public unix server otherwise known as a 'pubnix'. Anyone may become a free member to remotely access the server. Each member has their own little space on the server to do things with and run services. Different membership tiers unlock different perks and programs. Fortunately, one of the many provided to all members is the ability to create and curate their very own gemini capsule. Yay!
There are a variety of pubnixes which offer the ability to host gemini capsules for their users. I choose SDF patially out of ignorance as it was the first pubnix I encountered and liked what I saw. If you were to ask me with some hindsight and knowledge under my belt I would say I continue to stay with it because it has proven its longevity and stability in the long run. Its arguably one of the oldest pubnixes established in the 90s. While I eventually plan to create my own server to host my capsule on, Im happy with my experience so far. I have learned alot about UNIX and capsule curation during my time with SDF.
Visit My Capsule Collection Index for a list of pubnixes which offer gemini capsule hosting
Let us take a moment to talk about hosting a server (or as we like to call them 'capsules' in the case of gemini servers). Servers are computers configured to accept network traffic from other networks. Any time you visit a site or download a file on the internet, your computer is connecting to another computer through networking black magic. There are generally two methods to creating servers.
Let us now take a look at the differences between the two.
Self hosting is a great way to run a capsule, and largely prefered given you have the technical know-how. Self Hosting is ideal for people who are familiar with computer networking, and have dabbled with things like operating systems, port forwarding, and registering a domain name.
You must have a dedicated computer running 24/7 and properly configured to accept public network traffic. Gemini is designed for low-end systems and because of that, a cheap single board computers (SBCs) is more than enough to host a capsule as well as many more services. SBCs also have the advantage of being extremely power efficent with the raspberry pi using a whopping 5 watts at max compared to a laptops consumption of 30-60 watts and a desktops consumption of many hundreds of watts. Still, any old desktop or laptop collecting dust somewhere made in the last 20 years will run a capsule server great if power consumption isnt a big concern.
Self hosting grants the most freedom as you directly have control over all the hardware and software. If you want to get more advanced with CGI scripts, being in control over what packages and programming librararies are on your server becomes vital. If you want to host large files like videos or audio, there are no file size limits besides size of hard drive you can afford to put in the server box.
From a privacy perspective self hosting is the best way to go because you have control over the logs and know how your information is being used. You cant really be sure how your data is being handled by companies and services regardless of their privacy policy, the only way to know is to handle it yourself.
However, as mentioned it takes some technical know-how and willingness to go through some trial and error just to get your server set up properly. It can take many hours of learning and tinkering with things before you even get around to writing gemini pages.
There is some inital cost of hardware provided you dont already have a spare computer lying around to tinker with. A server operator also needs to factor in long term maintenance cost of upkeep. For a non-techie person this is a lot to ask of them. Instead, there is a way to dip your toes into the Gemsphere quite a bit easier.
Remote hosting is a great alternative to self hosting. It is suited for beginners who dont have the technical know-how to set up a server, or for those who dont have the spare hardware or time to run one locally. Typically, a hosting company has a HUGE array of servers set up to go. They charge a few dollars per month to host your data/site on their servers. These kinds of servers are sometimes known as 'Virtual Private Servers' or 'VPS'.
Hosting companies typically have great user interfaces and make the process of setting up your services very easy. Network security is handled by the company provided. You dont have to deal with the headache or operating cost of maintaining the hardware.
But the downside is that youre paying to rent out someone elses hardware every month. Cash that could be spent investing in your own hardware. Its kind of like real-estate! There are also potential limitations to what can be done on a VPS. Things like arbitrary size limits to files that can be hosted, inablility to download specific libraries and dependancies.
Hosting services are also big targets for hackers. Theres a lot of juicy personal data and payment information for the taking. Network security is a fickle game of cat and mouse and all too often we see huge data breaches every year. Self-hosting mitigates this risk as hackers see much less reward for their efforts by targeting individual tiny servers. Its not really something to be worried about too much but keep it in mind.
Gemini capsules hosted by SDF fall are obviously remote hosted. You must access one of their remote servers under a user account in order to use their services. However, and this is the important part, SDF allows ANY user to create gemini capsules. Even the free membership level users. This makes SDF (and many other public unix servers) ideal gateways to creating and messing around with capsule creation without the burden of running your own dedicated server or paying someone else to do it. There are some hoops that you need to go through, and limits when it comes to file uploading and scripts. But its free and relatively simple. Cant ask for much more than that! So, ready to sign up?!
You can connect to the SDF UNIX server in a variety of ways depending on your operating system.
this video made by Wendy M. Chisholm
ssh new@sdf.org
the new@sdf.org part is a one time only thing. After you create the account and for all further connections use:
USERNAME@sdf.org
Then fill out all the information requested as you see fit. Make sure to read carefully as to not miss anything important.
Once you have your account made and you've logged into USERNAME@sdf.org through one of the methods above, hit enter twice to go past the introductory members list and moon phase screens until you get to a path of
sdf:/sdf/udd/s/USERNAME>
Welcome to SDF!
Heres a tip for fellow UNIX users. Once your SDF account is up and running I recommend editing your local computers ./bashrc config file and creating a shorthand alias at the end of it such as
alias sdf='ssh USERNAME@sdf.org'
So you dont have to type out the long form command each time you want to connect.
I also advise generating a SSH keypair between your local computer and SDF. That way you dont need to enter the password over and over. To learn more read here:
SDF Wiki entry on SSH public key authentication
DigitalOcean article on SSH keys
From this point it could be wise to learn basic navigation and file manipulation commands. Here is a very short list of commonly used commands.
The mkgopher command "chmod" is frequently used to set permissions on ALL new files & directories
Here for more information on UNIX commands
Here for more information on SDF exclusive commands
After getting familiar with the basic commands its time to start making the capsule. First we need to run the mkgopher command. The command is SDF exclusive, built to help set up the capsule directory and apply proper file permissions. Historically it was originally designed for setting up a gopherhole on the gopher protocol, but has recently been reworked to include gemini capsules.
mkgopher
you should see this line At the bottom letting you know that you are now working within the program:
MKGOPHER>
While not strictly necessary, I recommend running the "help" command just to see all the paramaters you can use.
Next we will run the setup command
MKGOPHER> setup
This will create a new directory in the home folder, "gopher". The "gopher" directory is where we will store all the delicious .gmi text files that makes up the capsule. The name is for historical reasons, dont let that fool you.
Before exiting out of the program, there is one other command that you need to be aware of, "chmod". It is important to run this !!!EVERY TIME!!! you create a new .gmi text file, upload an image, or do anything with the capsule directory.
MKGOPHER> chmod
YOU MUST RUN THIS EVERY TIME YOU ADD NEW FILES TO THE CAPSULE OR THE PAGE/FILE WILL NOT LOAD. If your new capsule page or uploaded photo isnt working, its probably because you need to hop into mkgopher and run chmod.
Now that were done with MKGOPHER, run this to exit the program.
MKGOPHER> quit
Chapter 3: Making your first Gemini Capsule Page
If all went well, there is now a new folder in the home directory called "gopher". Make sure its there by running the ls command
ls
To enter the gopher folder run:
cd gopher
From now on this is where all your gemini capsule files will be made and kept.
The gopher subdirectory is actually a shortcut. Its real location adress in the server is ftp/pub/users/USERNAME. When I first became a member, i made the mistake of trying to put files directly into the real directory and this gave errors. It caused me many days of headache since the SDF wiki page on gemini makes no mention of this. Instead suggesting you to cd into the real directory and create a .gmi page from there. Use the gopher folder in your user root directory for everything.
make sure you are in the gopher directory. then run the command:
nano index.gmi
This will open up a basic text editor called nano, then create a blank text file called "index" formatted in gemtext format .gmi. The index.gmi file is the core of your capsules directory, and the first file called upon when looking up a capsules url.
From this point I advise putting in this sample block of text if you want a simple copy paste page. Feel free to put in whatever you want though. Refer to the link about gemtext at the end for more information on proper formatting in the gemini markdown language.
For those who have never copy/ pasted in a terminal its actually ctrl+shift+c and ctrl+shift+p
# USERNAME'S CAPSULE! (Level 1 Header) > Est. [dd/mm/yy] (quote) This is my first page in gemini space! Thanks for stopping by 0/ ## Some Links (Level 2 Header) => URL_LINK [user friendly title] => //sdf.org/smokey/ To Smokeys Capsule! => ../ To SDF Cluster => //gem.sdf.org To SDF Meta Array (Dont need the gemini: part) ./ and ../ are shortcuts for moving up either one directory up or to the root directory ### Contact Info (Level 3 Header) Email: XMPP:
After filling out your index.gmi and customizing it to your liking, hit the keys Ctrl-o to save the changes then Ctrl-x to exit.
Now that our new index.gmi file is made and ready to go, we need to give it the proper permissions. Run the command:
mkgopher
Once inside the program, run
MKGOPHER> chmod
your index.gmi file should now have the proper file permissions. exit mkgopher with the command:
quit
Now the capsule should be reachable.
Run this command to see your new index.gmi text file listed in the gopher directory:
ls
Its a good idea to make several subdirectories to keep your capsule organized. A gemlog folder to keep your logs in for example. Inside each sub-directory youll want to make a new index. Dont forget to mkgopher> chmod afterwards.
From this point if all went well, you SHOULD be able to access the new capsule from your gemini browser of choice. Connect to this url:
gemini://sdf.org/USERNAME/
The capsule should also show up at the SDF cluster homepage
gemini://gem.sdf.org The SDF Meta Array for advanced users
The cluster is for the regular SDF users, while the Meta Array is for paid META users.
More information on the Meta Array can be found here
While gemini is a text based protocol, many graphical browsers such as Lagrange are able to download and display images and other various forms of media from capsules. For the longest time I thought it wasnt possible to host images on SDF because none of what I tried seemed to work. As it turns out, there is an incredibly small image limit of 27 kilobytes. For whatever reason any more than that seems to cause an error. I am unsure if this is a bug or a known limit, but I didnt see any documentation about it on the wiki.
In order to get the image small enough to meet the 27kb criteria, I used GIMP to scale it down to 400 width x 300 height, and when exporting to .jpg, set the "quality" slider to 7 (out of 100). Its not an ideal way to share pictures, but I suppose it fits with the low end bandwith / hardware spirit of gemini.
I recommend making a "pictures" directory inside the gopher directory. To send images to the SDF server, I use the command:
sftp USERNAME@sdf.org
it will then ask you for your password, and you will land in the home directory. cd to the location of your pictures directory.
then run the command
put /your/local/file/location/file.jpg
Learn more about sftp commands here
Alright, thats the basics of it. I believe this guide will do its job to help get you on the right path. Please let me know if this helped! Thank You for reading, and thanks to sdf for their generosity in hosting!
SDF Wiki article on setting up a gemini server
