op public repos

Blob

Date:: Wed Oct 13 20:52:19 2021 UTC
Message:: more small improvements for the quickstart
Actions:: History | Blame | Raw File
1 <!doctype html>
2 <html lang="en">
3   <head>
4     <title>gmid quickstart</title>
5     <meta charset="utf8" />
6     <meta name="viewport" content="width=device-width, initial-scale=1" />
7     <style>
8     body {
9       font-family: monospace;
10       font-size: 14px;
11       max-width: 780px;
12       margin: 0 auto;
13       padding: 20px;
14       padding-bottom: 80px;
15     }
16 
17     h1::before {
18       content: "# ";
19     }
20 
21     h2 {
22       margin-top: 40px;
23     }
24 
25     h2::before {
26       content: "## ";
27     }
28 
29     h3::before {
30       content: "### ";
31     }
32 
33     blockquote {
34       margin: 0;
35       padding: 0;
36     }
37 
38     blockquote::before {
39       content: "> ";
40     }
41 
42     blockquote p {
43       font-style: italic;
44       display: inline;
45     }
46 
47     p.link::before {
48       content: "→ ";
49     }
50 
51     strong::before { content: "*" }
52     strong::after  { content: "*" }
53 
54     hr {
55       border: 0;
56       height: 1px;
57       background-color: #222;
58       width: 100%;
59       display: block;
60       margin: 2em auto;
61     }
62 
63     img {
64       border-radius: 5px;
65     }
66 
67     pre {
68       overflow: auto;
69       padding: 1rem;
70       background-color: #f0f0f0;
71       border-radius: 3px;
72     }
73 
74     pre.banner {
75       display: flex;
76       flex-direction: row;
77       justify-content: center;
78     }
79 
80     code, kbd {
81       color: #9d109d;
82     }
83 
84     img {
85       display: block;
86       margin: 0 auto;
87       max-width: 100%;
88     }
89 
90     @media (prefers-color-scheme: dark) {
91       body {
92         background-color: #222;
93         color: white;
94       }
95 
96       a {
97         color: aqua;
98       }
99 
100       hr {
101         background-color: #ddd;
102       }
103 
104       pre {
105         background-color: #353535;
106       }
107 
108       code, kbd {
109         color: #ff4cff;
110       }
111     }
112 
113     @media (max-width: 400px) {
114       pre.banner { font-size: 9px; }
115     }
116 
117     @media (max-width: 500px) {
118       pre.banner { font-size: 10px; }
119     }
120     </style>
121   </head>
122   <body>
123     <header>
124       <nav>
125         <a href="/">Home</a> |
126         <a href="contrib.html">contrib</a> |
127         Quickstart |
128         <a href="gmid.1.html">docs</a>
129       </nav>
130     </header>
131     <h1>gmid quickstart</h1>
132     <p>gmid can be run in two different “modes”:</p>
133     <dl>
134       <dt>configless:</dt>
135       <dd>
136         a quick way to serve a directory tree from the shell, useful
137         for testing a capsule before uploading it
138       </dd>
139       <dt>daemon mode:</dt>
140       <dd>
141         gmid reads the configuration file and runs in the background
142       </dd>
143     </dl>
144     <p>To run gmid in the “configless” mode, just type:</p>
145     <pre>$ gmid path/to/dir</pre>
146     <p>
147       gmid will then generate a certificate inside ~/.local/share/gmid
148       and serve the given directory locally.
149     </p>
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>
152     <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
156       enough to start:
157     </p>
158     <pre># /etc/gmid.conf
159 
160 server "example.com" {
161 	cert "/etc/ssl/example.com.pem"
162 	key  "/etc/ssl/private/example.com/key"
163 
164 	# path to the root directory of your capsule
165 	root "/var/gemini/example.com"
166 }</pre>
167     <p>
168       A certificate is needed for the capsule.  Generate one for
169       e.g. using
170       <a href="https://git.omarpolo.com/gmid/tree/contrib/gencert">contrib/gencert</a>:
171     </p>
172     <pre>$ ./contrib/gencert example.com
173 Generating a 4096 bit RSA private key
174 .................................................++++
175 ..........++++
176 writing new private key to './example.com.key'
177 -----
178 
179 Generated files:
180         ./example.com.pem : certificate
181         ./example.com.key : private key</pre>
182     <p>
183       Move ‘example.com.pem’ and ‘example.com.key’ to a safe place and
184       double check that the ‘cert’ and ‘key’ options in the
185       configuration points to these files.
186     </p>
187     <p>For example, save them in ‘/etc/ssl/’ (as root)</p>
188     <pre># mkdir -p /etc/ssl/private
189 # chown 700 /etc/ssl/private
190 # mv example.com.pem /etc/ssl/
191 # mv example.com.key /etc/ssl/private/</pre>
192     <p>
193       Make sure that the ‘cert’ and ‘key’ options in the configuration
194       file points to these files.
195     </p>
196     <p>Then running gmid is as easy as</p>
197     <pre>$ gmid -c /etc/gmid.conf</pre>
198     <p>Congratulations, your capsule is online!</p>
199     <h2>Securing your gmid installation</h2>
200     <p>
201       gmid employs various techniques to prevent the damage caused by
202       bugs, but some steps needs to be done manually.
203     </p>
204     <p>
205       If gmid was installed from your distribution package manager,
206       chance are that it already does all of this and is also
207       providing a service to run gmid automatically (e.g. a rc script,
208       a systemd unit file …)  Otherwise, it’s heavily suggested to
209       create at least a dedicated user.
210     </p>
211     <h3>A dedicated user</h3>
212     <p>
213       Ideally, gmid should be started as root and drop privileges to a
214       local user.  This way, the certificates can be readable only by
215       root.  For example, on GNU/linux systems a ‘gmid’ user can be
216       created with:
217     </p>
218     <pre># useradd --system --no-create-home -s /bin/nologin -c "gmid Gemini server" gmid</pre>
219     <p>
220       Please consult your OS documentation for more information on the
221       matter.
222     </p>
223     <p>
224       The configuration then needs to be adjusted to include the
225       ‘user’ directive at the top:
226     </p>
227     <pre># /etc/gmid.conf
228 user "gmid"
229 
230 server "example.com" { … }</pre>
231     <p>
232       gmid then needs to be started with root privileges, but will
233       then switch to the provided user automatically.  If by accident
234       the ‘user’ option is omitted and gmid is running as root, it
235       will complain loudly in the logs.
236     </p>
237     <h3>chroot</h3>
238     <p>
239       It’s a common practice for system daemons to chroot themselves
240       into a directory.  From here on I’ll assume /var/gemini, but it
241       can be any directory.
242     </p>
243     <p>
244       A chroot on UNIX-like OS is an operation that changes the
245       “apparent” root directory (i.e. the “/”) from the current
246       process and its child.  Think of it like imprisoning a process
247       into a directory and never letting it escape until it
248       terminates.
249     </p>
250     <p>
251       Using a chroot may complicate the use of CGI scripts, because
252       then all the dependencies of the scripts (sh, perl, libraries…)
253       need to be installed inside the chroot too.  For this very
254       reason gmid supports FastCGI.
255     </p>
256     <p>
257       The chroot feature requires a dedicate user, see the previous
258       section.
259     </p>
260     <p>
261       To chroot gmid inside a directory, use the ‘chroot’ directive in
262       the configuration file:
263     </p>
264     <pre># /etc/gmid.conf
265 
266 user "gmid"
267 
268 # the given directory, /var/gemini in this case, must exists.
269 chroot "/var/gemini"</pre>
270     <p>
271       Note that once ‘chroot’ is in place, every ‘root’ directive is
272       implicitly relative to the chroot, but ‘cert’ and ‘key’ aren’t!
273     </p>
274     <p>For example, given the following configuration:</p>
275     <pre># /etc/gmid.conf
276 
277 user "gmid"
278 chroot "/var/gemini"
279 
280 server "example.com" {
281 	cert "/etc/ssl/example.com.pem"
282 	key  "/etc/ssl/example.com.key"
283 	root "/example.com"
284 }</pre>
285     <p>
286       The certificate and the key path are the specified ones, but the
287       root directory of the virtual host is actually
288       “/var/gemini/example.com/”.
289     </p>
290   </body>
291 </html>