content/blog/2021-04-17-gemini-server.org

  1#+date:        <2021-04-17 Sat 00:00:00>
  2#+title:       Gemini Server Installation and Configuration Procedures Using Agate
  3#+description: Detailed directives for installation and configuration of a Gemini protocol server on Ubuntu, including network security and firewall setup.
  4#+slug:        gemini-server
  5#+filetags:    :gemini:server:agate:
  6
  7* Similar Article Available
  8
  9To read more about Gemini and ways to test out this new protocol without
 10your own server, see my previous post
 11[[../launching-a-gemini-capsule/][Launching a Gemini Capsule]].
 12
 13* Preparation
 14
 15This guide assumes you have access to a server accessible to the world
 16through a public IP address and that you own a domain name used for this
 17Gemini capsule.
 18
 19* Getting Started with Agate
 20
 21We are going to use [[https://github.com/mbrubeck/agate][Agate]] for
 22this tutorial. This is a basic Gemini server written in Rust. It takes
 23very little time and maintenance to get it running.
 24
 25* Install Dependencies
 26
 27First, you will need to install the Rust package for your system. On
 28Ubuntu, use the following commands (remember to use =sudo= if you are
 29not the root user). The Rust installation will give you options to
 30customize the installation; I used the default installation options.
 31
 32#+begin_src sh
 33sudo apt update && sudo apt upgrade -y
 34curl https://sh.rustup.rs -sSf | sh
 35#+end_src
 36
 37Remember to configure your shell with the new configuration:
 38
 39#+begin_src sh
 40source $HOME/.cargo/env
 41#+end_src
 42
 43Before we install agate, make sure you have the =gcc= package installed:
 44
 45#+begin_src sh
 46sudo apt install gcc
 47#+end_src
 48
 49Next, you'll need to install the agate executable with Rust's Cargo
 50package maintainer:
 51
 52#+begin_src sh
 53cargo install agate
 54#+end_src
 55
 56* Create Symlinks
 57
 58Once Cargo has finished installing all the required packages, symlink
 59the executable to your $PATH.
 60
 61#+begin_src sh
 62sudo ln -s $HOME/.cargo/bin/agate /usr/local/bin/agate
 63#+end_src
 64
 65* Using Agate's Built-In Installation Tool
 66
 67If you're running Ubuntu or Debian, use the Debian installation script
 68found in Agate's GitHub repository, under the =tools/debian= folder.
 69
 70#+begin_src sh
 71git clone https://github.com/mbrubeck/agate
 72cd agate/tools/debian
 73sudo ./install.sh
 74#+end_src
 75
 76* Configure the Gemini Service
 77
 78We have a little more to do, but since this script tries to immediately
 79run the service, it will likely fail with an exit code. Let's add our
 80finishing touches. Edit the following file and replace the hostname with
 81your desired URL. You can also change the directory where content will
 82be served.
 83
 84#+begin_src sh
 85sudo nano /etc/systemd/system/gemini.service
 86#+end_src
 87
 88#+begin_src sh
 89# Edit these lines to whatever you want - see the next code block for my personal configuration.
 90WorkingDirectory=/srv/gemini
 91ExecStart=agate --hostname $(uname -n) --lang en
 92#+end_src
 93
 94This is my personal config:
 95
 96#+begin_src sh
 97WorkingDirectory=/var/gemini/
 98ExecStart=agate --hostname gemini.example.com --lang en
 99#+end_src
100
101Since we've altered the systemd configuration files, we have to reload
102the daemon. Let's do that, restart our service, and check its status.
103
104#+begin_src sh
105sudo systemctl daemon-reload
106sudo systemctl restart gemini.service
107sudo systemctl status gemini.service
108#+end_src
109
110* Fixing Systemd Errors
111
112If you're still getting errors, the installation process may not have
113properly enabled the gemini service. Fix it with the following commands.
114
115#+begin_src sh
116sudo systemctl enable gemini.service
117sudo systemctl restart gemini.service
118sudo systemctl status gemini.service
119#+end_src
120
121* Firewall Rules
122
123Great! Our server is now functional and running. The first consideration
124now is that you need to be able to access port 1965 on the server. If
125you have a firewall enabled, you'll need to open that port up.
126
127#+begin_src sh
128sudo ufw allow 1965
129sudo ufw reload
130#+end_src
131
132* Creating Content
133
134Let's create the Gemini capsule. Note that wherever you set the
135WorkingDirectory variable to earlier, Agate will expect you to put your
136Gemini capsule contents in a sub-folder called "content." So, I place my
137files in "/var/gmi/content." I'm going to create that folder now and put
138a file in there.
139
140#+begin_src sh
141sudo mkdir /var/gemini/content
142sudo nano /var/gemini/content/index.gmi
143#+end_src
144
145You can put whatever you want in the "index.gmi" file, just make sure
146it's valid Gemtext.
147
148* The Results
149
150To view the results, you can use a Gemini browser, such as
151[[https://gmi.skyjake.fi/lagrange/][Lagrange]] or
152[[https://github.com/makeworld-the-better-one/amfora][amfora]].