💾 Archived View for edaha.org › oracle-ci-how-to.gmi captured on 2022-03-01 at 15:00:26. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2021-11-30)
-=-=-=-=-=-=-
This site (edaha.org) is hosted for free by using Oracle Cloud's 'Always Free' tier of services. This includes:
This guide aims to walk you through the steps needed to get started in Gemini space the same way I did. It's written for absolute beginners and follows a step-by-step approach.
In order to follow this guide, you'll need:
The first thing you'll need to do is register for an Oracle Cloud account:
Follow the steps for registration on the link above. Unfortunately, you do need to provide a valid credit card for registration. It won't be charged, however.
If you don't want to use Oracle (fuck Larry Ellison), the only other free options are:
AWS (12 month limit. 1 t2.micro VM, 1GB RAM, 20GB storage, 15GB transfer)
Azure (12 month limit, 1 B1S VM, 1GB RAM, 2x64GB storage, 15GB transfer)
GCP (no limit, 1 f1-micro VM, 0.6GB RAM, 30GB storage, 1GB transfer)
Oracle has the following specs:
Somehow, Oracle has the best value.
Oracle uses "Compartments" to separate groups of services from one another. We're going to make one to hold all of our Gemini services.
This part is optional, but if you plan to play with other things within OCI, it's nice to ensure all our Gemini items will be on their own.
You're done! From here on, we'll ensure that any instances or networks that we make exist within this compartment. If we don't, they won't be able to talk to each other.
Next, we'll create the Virtual Cloud Network that the VM will use to access the internet. We will come back to it after we set up our VM to adjust some firewall rules, but for now, we just need to get one running.
At this point, you'll be shown the status as each piece of the VCN is provisioned. We're done here (for now!)
Now we're going to create an Ubuntu VM that'll run our gemini server. Oracle refers to these as "Instances".
At this point, your VM will start to be provisioned! Wait on this page until you see "Public IP Address" under "Instance Access". Copy that, we'll need it soon!
As mentioned earlier, the standard VCN is extremely locked down, which is good! If you want to test it, try to ping the IP address of your server -- you won't get a response as most ICMP traffic is blocked.
However, this means that we have to explicitly allow gemini traffic through it. Here's what we can do:
You're done! We basically just said "allow any requests on port 1965 to enter our network". This is necessary as, by default, gemini hosts serve to port 1965.
Now that we've finished getting our network and VM provisioned, we're finally ready to dive in and start to work on getting the right software running on our server. We'll be using Putty (assuming Windows) to access our server remotely and install Jetforce on it.
PuTTY: a free SSH and Telnet client
Before we can connect, we have one intermediate step, which is to convert the private key generated by Oracle (filetype: .key) to one that's usable by PuTTY (.ppk). To do this, we'll use PuTTYgen, which was included with your PuTTY install:
You don't need to click "Save public key" as it'll be the same as what you got from Oracle. We'll use the .ppk in the next step.
[1]: If you didn't download it, you're SOL. You'll need to terminate your Instance and create a new one.
If everything was successful, you should now see a note that you're logging in and authenticating using the private key you selected. Once you see a welcome message and a shell prompt, *hacker voice* you're in!
Before we can have fun, we need to take care of a few maintenance tasks first. Run all of the following commands.
$ sudo apt update $ sudo apt upgrade -y
The above commands update all local packages, so we're ready to start!
Just like the VCN, the VMs come with incredibly restrictive firewall rules, which is still good! You should always operate as if there is no trust, even within your own network. Only open what you need!
To see them, you can run:
$ sudo iptables -L INPUT
We want to add one that allows TCP traffic on port 1965, just like before:
$ sudo iptables -I INPUT 1 -p tcp --dport 1965 -j ACCEPT $ sudo iptables -L INPUT
If done correctly, your table should now look like this:
$ sudo iptables -I INPUT 1 -p tcp --dport 1965 -j ACCEPT $ sudo iptables -L INPUT Chain INPUT (policy ACCEPT) target prot opt source destination ACCEPT tcp -- anywhere anywhere tcp dpt:1965 ACCEPT all -- anywhere anywhere state RELATED,ESTABLISHED ACCEPT icmp -- anywhere anywhere ACCEPT all -- anywhere anywhere ACCEPT udp -- anywhere anywhere udp spt:ntp ACCEPT tcp -- anywhere anywhere state NEW tcp dpt:ssh REJECT all -- anywhere anywhere reject-with icmp-host-prohibited
Now we want to save them so that they're loaded automatically, as iptables edits are temporary by default. The ubuntu images come pre-installed with iptables-persistent, which makes this simple:
$ sudo iptables-save -f /etc/iptables/rules.v4
iptables peristent will load the file above by default on system boot, so they'll remain open even if you need to restart the VM.
Gemini mandates encrypted connections, so we'll eventually need a TLS certificate to provide for our server. For now, we're only going to self-sign.
In the code below, replace {hostname} with the domain you will eventually serve Gemini from:
$ openssl req -newkey rsa:2048 -nodes -keyout {hostname}.key \
-nodes -x509 -out {hostname}.crt -subj "/CN={hostname}"
This will give you a self-signed certificate and key file. You'll need these both when we launch the server later.
_Finally_, we're at the point of installing Jetforce. If you thought it took a while to get here reading, imagine me having to re-run all these commands while writing!
Despite the instructions, I had no luck getting jetforce installed using pip, but we still need it for dependencies in jetforce. We'll be installing from source, so run these commands to do so and create the base data directory for jetforce:
$ sudo apt install python3-pip -y $ git clone https://github.com/michael-lazar/jetforce $ cd jetforce $ python3 setup.py install $ sudo mkdir /var/gemini $ cd ~
At this point, we've done everything we need to do... except start the server! We are going to run it on our IP first, so for now, run the following command, replacing {ip} with your server's public IP
$ sudo jetforce --host 0.0.0.0 --hostname {ip}
In your SSH session, you should now see the following:
$ ubuntu@gemini-test:~$ jetforce --host 0.0.0.0 --hostname {ip}
Generating ad-hoc certificate files...
You are now riding on...
_________ _____________
______ /______ /___ __/_______________________
___ _ /_ _ \ __/_ /_ _ __ \_ ___/ ___/ _ \
/ /_/ / / __/ /_ _ __/ / /_/ / / / /__ / __/
\____/ \___/\__/ /_/ \____//_/ \___/ \___/
An Experimental Gemini Server, v0.8.1
https://github.com/michael-lazar/jetforce
Server hostname is {ip}
TLS Certificate File: /tmp/{ip}.crt
TLS Private Key File: /tmp/{ip}.key
Listening on 0.0.0.0:1965
If so, congrats! Your Jetforce server is running. If you have followed everything up to this point, you should now be able to navigate to your server's IP in your favorite Gemini client and you should get an empty directory listing. Once you do, if you look back at your SSH client, you should see a line that looks something like this below the above, where x.x.x.x is your own IP:
x.x.x.x [14/Jan/2021:04:49:13 +0000] "gemini://{ip}" 20 text/gemini
Now press CTRL+C to end the Jetforce program. We've been able to confirm that it's up, running, and accessible from the internet, so we're going to take it down and put on the finishing touches.
To have Jetforce work on our domain, we need to feed it a few additional parameters when it starts up. Below, replace {hostname} with the domain that you'll host this at:
$ jetforce \
--host 0.0.0.0 \
--hostname {hostname} \
--tls-certfile {hostname}.crt \
--tls-keyfile {hostname}.key &
After running those commands, you should see the same Jetforce banner, but with the hostname and certificate/key files above. The `&` at the end allows you to exit back to the terminal. If you try to open your server's URL in your Gemini client, you should see the same error as before.
For this part, there's not much I can write out: you at this point need to go to your domain registrar and use their tools to add a single A record to your domain with the IP address of your server. Once that's done, you need to wait until the DNS changes propagate. Within a few hours, you should be able to access your gemini server directly!
If you've followed every step up to this point, you should have a functioning, accessible gemini server. Of course, you don't have any content -- if you navigate to your domain, you should only see an empty directory listing.
To add content to your server, you need to make .gmi files in /var/gemini/. The example below opens nano to edit /var/gemini/index.gmi:
$ sudo nano /var/gemini/index.gmi
Write some text (hello world!) and press CTRL-O to save and CTRL-X to exit nano. If you refresh the page in your Gemini client, you should see your new content!
This gives a quick way to get started with your first gemini server. However, this isn't a permanent solution. In a future guide I'll cover making Jetforce start automatically on boot, and locking down the server process's permissions to reduce any security risk.
Inspiration for this guide came from matrix.org's article on making a "Free Small Matrix Server":
Free Small Matrix Server | Matrix.org