4 <title>gmid quickstart</title>
5 <meta charset="utf8" />
6 <meta name="viewport" content="width=device-width, initial-scale=1" />
9 font-family: monospace;
51 strong::before { content: "*" }
52 strong::after { content: "*" }
57 background-color: #222;
70 background-color: #f0f0f0;
77 justify-content: center;
90 @media (prefers-color-scheme: dark) {
92 background-color: #222;
101 background-color: #ddd;
105 background-color: #353535;
113 @media (max-width: 400px) {
114 pre.banner { font-size: 9px; }
117 @media (max-width: 500px) {
118 pre.banner { font-size: 10px; }
125 <a href="/">Home</a> |
126 <a href="contrib.html">contrib</a> |
128 <a href="gmid.1.html">docs</a>
131 <h1>gmid quickstart</h1>
132 <p>gmid can be run in two different “modes”:</p>
136 a quick way to serve a directory tree from the shell, useful
137 for testing a capsule before uploading it
139 <dt>daemon mode:</dt>
141 gmid reads the configuration file and runs in the background
144 <p>To run gmid in the “configless” mode, just type:</p>
145 <pre>$ gmid path/to/dir</pre>
147 gmid will then generate a certificate inside ~/.local/share/gmid
148 and serve the given directory locally.
150 <h2>Setting up a capsule with gmid</h2>
151 <p>To host a Gemini capsule you need to run gmid in “daemon” mode.</p>
153 To run gmid in daemon mode a configuration file is needed. The
154 format of the configuration file is described in the manpage and
155 is quite flexible, but something like the following should be
158 <pre># /etc/gmid.conf
160 server "example.com" {
161 cert "/path/to/certificate"
162 key "/path/to/private-key"
163 root "/var/gemini/example.com"
166 You also need to generate a certificate for the capsule. A
167 X.509 (TLS) certificate can be generated for e.g. with
168 <a href="https://git.omarpolo.com/gmid/tree/contrib/gencert">contrib/gencert</a>:
170 <pre>$ ./contrib/gencert example.com
171 Generating a 4096 bit RSA private key
172 .................................................++++
174 writing new private key to './example.com.key'
178 ./example.com.pem : certificate
179 ./example.com.key : private key</pre>
181 Optionally, move ‘example.com.pem’ and ‘example.com.key’ to
185 Make sure that the ‘cert’ and ‘key’ options in the configuration
186 file points to these files.
188 <p>Then running gmid is as easy as</p>
189 <pre>$ gmid -c /etc/gmid.conf</pre>
190 <p>Congratulations, your capsule is online!</p>
191 <h2>Securing your gmid installation</h2>
193 gmid employs various techniques to prevent the damage caused by
194 bugs, but some steps needs to be done manually.
197 If gmid was installed from your distribution package manager,
198 chance are that it already does all of this and is also
199 providing a service to run gmid automatically (e.g. a systemd
200 unit file, a rc script, …) Otherwise, it’s heavily suggested to
201 create at least a dedicated user.
203 <h3>A dedicated user</h3>
205 Ideally, gmid should be started as root and drop privileges to a
206 local user. This way, the certificates can be readable only by
207 root. For example, on GNU/linux systems a ‘gmid’ user can be
210 <pre># useradd --system --no-create-home -s /bin/nologin -c "gmid Gemini server" gmid</pre>
212 Please consult your OS documentation for more information on the
216 The configuration then needs to be adjusted to include the
217 ‘user’ directive at the top:
219 <pre># /etc/gmid.conf
222 server "example.com" { … }</pre>
224 gmid then needs to be started with root privileges, but will
225 then switch to the provided user automatically. If by accident
226 the ‘user’ option is omitted and gmid is running as root, it
227 will complain loudly in the logs.
231 It’s a common practice for system daemons to chroot themselves
232 into a directory. From here on I’ll assume /var/gemini, but it
233 can be any directory.
236 A chroot on UNIX-like OS is an operation that changes the
237 “apparent” root directory (i.e. the “/”) from the current
238 process and its child. Think of it like imprisoning a process
239 into a directory and never letting it escape until it
243 Using a chroot may complicate the use of CGI scripts, because
244 then all the dependencies of the scripts (sh, perl, libraries…)
245 need to be installed inside the chroot too. For this very
246 reason gmid supports FastCGI.
249 The chroot feature requires a dedicate user, see the previous
253 To chroot gmid inside a directory, use the ‘chroot’ directive in
254 the configuration file:
256 <pre># /etc/gmid.conf
260 # the given directory, /var/gemini in this case, must exists.
261 chroot "/var/gemini"</pre>
263 Note that once ‘chroot’ is in place, every ‘root’ directive is
264 implicitly relative to the chroot, but ‘cert’ and ‘key’ aren’t!
266 <p>For example, given the following configuration:</p>
267 <pre># /etc/gmid.conf
272 server "example.com" {
273 cert "/etc/ssl/example.com.pem"
274 key "/etc/ssl/example.com.key"
278 The certificate and the key path are the specified ones, but the
279 root directory of the virtual host is actually
280 “/var/gemini/example.com/”.