💾 Archived View for sdf.org › smokey › gemlog › 2021-12-01-gemsdf.gmi captured on 2022-01-08 at 13:44:35. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2021-12-17)
-=-=-=-=-=-=-
Hello! Today im going to teach you how to set up a gemini capsule through sdf.org I write guide to be streamlined, giving you simple, clear to understand instructions to make the process as painless and non-convoluted as possible. The goal is to 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).
SDF is a a non-profit organization that maintains a public unix server. Anyone may become a member to remotely access the server, each member has their own little space to do things with. One of the many provided to all members is the ability to create their very own gemini capsule. Yay!
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) There are generally two methods to hosting a server.
Self hosting is a great way to run a capsule, and largely prefered given you have the technical know-how. Ideal for people who are familiar with computer networking, and have dabbled with port forwarding. Self hosting requires you have a dedicated computer running 24/7 and configured to accept public network traffic. Gemini is designed for low-end systems in mind, so a raspberry pi or other cheap single board computers (SBCs) is more than enough. Self hosting grants the most freedom as you directly have control over all the hardware and software. However, as mentioned it takes some technical know-how just to get everything set up before you can 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 needs to factor in long term power consumption into the 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. Suited for beginners who dont have the technical know-how to set up a server, or for those who dont have the spare hardware to run one. Typically, a hosting company charges a few dollars per month for remote access to their private servers (sometimes known as Virtual Private Servers or 'VPS') which you run your capsule from. Network security is handled by the company provided. You dont have to deal with the headache of maintaining your server or dealing with potential network attacks. But the downside is that youre paying to rent out someone elses hardware, cash that could be spent investing in your own hardware. There are also potential limitations to what can be done on a VPS.
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. Buuut 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.
this video made by Wendy M. Chisholm
ssh new@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 open terminal with a path of
sdf:/sdf/udd/s/USERNAME>
Welcome to SDF!
A tip for fellow GNU/Linux users: later on once you get your own account I recommend editing your ./bashrc and creating a shorthand alias 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. Also, set up ssh to automatically log in to sdf so you dont need to enter the password every time.
Once youre at this point, run the program
mkgopher
mkgopher is a program meant to help you automatically set up the gemini capsule directory. Historically it was originally designed for the gopher protocol, but has been reworked for gemini.
you should see the line
MKGOPHER>
at the bottom letting you know that you are now working within the program. While not necessary, I recommend running the "help" command just to see all the paramaters you can use.
Next we will run
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.
Before exiting out of the program, there is one other command that you need to be aware of, as it is important to run every time you create a new text file or do anything with the gopher directory.
chmod
YOU MUST RUN THIS EVERY TIME YOU ADD NEW FILES TO THE CAPSULE OR THE PAGE/FILE WILL NOT LOAD. This command applies the proper permissions to the files for them to work and need to be manually applied. If your new capsule page isnt working, its probably because you need to hop into mkgopher and run this command.
Now that were done with MKGOPHER, run this to exit the program.
quit
There is now a new folder in the home directory called "gopher". Verify its there by running the command
ls
This is where all your gemini capsule files will be made and kept. To enter the gopher folder run:
cd gopher
The gopher folder in the home directory is actually a shortcut. Its real location in the server is at ftp/pub/users/USERNAME. I was not aware of this, so made the mistake of trying to put files in the real directory which gave errors. This caused me many days of headache since the SDF gemini wiki page makes no mention of this, instead suggesting you to nano into the real directory. I stumbled upon this useful tidbit over at the sdf gopher wiki page by pure luck. Hopefully this helps clear confusion. Use the gopher folder in your root directory for everything.)
make sure you are in the gopher directory. then run the command:
nano index.gmi
This will open up a text editor "nano" and create a blank text file called "index" formatted in gemtext. The index.gmi file is the core of your capsule, and the first file called upon when looking up a capsules url. Each time you make a sub-directory inside the gopher directory (say, a directory for gemlogs, a directory for pictures, ect youll want to make an index.gmi for that directory.
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.
(Tip: For those who have never copy/ pasted in a terminal its actually ctrl+shift+c and ctrl+shift+p)
#My First page! (Header) This is my first page in Gemini space! => link user friendly title 1 => link link user friendly title 2 => ../ Back To SDF Cluster Homepage (../ is a shortcut for going a directory up)
after filling out your index.gmi, 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
chmod
exit mkgopher with the command
quit
Now the permissions are properly set up, and the capsule should be reachable.
Run this command to see your new index.gmi text file listed in the gopher directory:
ls
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
