cmc/cleberg.net

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