op public repos

Blob

Date:: Sat Oct 9 16:30:36 2021 UTC
Message:: add the Quickstart page
Actions:: History | Blame | Raw File
1 <!doctype html>
2 <html lang="en">
3   <head>
4     <title>gmid | contrib</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 serving the given directory locally.
149     </p>
150     <p>
151       To run gmid in daemon mode a configuration file is needed.  The
152       format of the configuration file is described in the manpage and
153       is quite flexible, but for simple setup something like the
154       following should be enough:
155     </p>
156     <pre># /etc/gmid.conf
157 
158 server "example.com" {
159 	cert "/path/to/certificate"
160 	key  "/path/to/private-key"
161 	root "/var/gemini/example.com"
162 }</pre>
163     <p>
164       A X.509 (TLS) certificate can be generated using
165       <a href="https://git.omarpolo.com/gmid/tree/contrib/gencert">contrib/gencert</a>:
166     </p>
167     <pre>$ ./contrib/gencert example.com
168 Generating a 4096 bit RSA private key
169 .................................................++++
170 ..........++++
171 writing new private key to './example.com.key'
172 -----
173 
174 Generated files:
175         ./example.com.pem : certificate
176         ./example.com.key : private key</pre>
177     <p>
178       Optionally copy ‘example.com.pem’ and ‘example.com.key’ to
179       another location.
180     </p>
181     <p>
182       Make sure that the ‘cert’ and ‘key’ options in the configuration
183       file points to these files.
184     </p>
185     <p>Then running gmid is as easy as</p>
186     <pre>$ gmid -c /etc/gmid.conf</pre>
187     <h2>Securing your gmid installation</h2>
188     <p>
189       gmid employs various techniques to prevent the damage caused by
190       bugs, but some steps needs to be done manually.
191     </p>
192     <p>
193       If gmid was installed from your distribution package manager,
194       chance are that it already does all of this and is also
195       providing a service to run gmid automatically (e.g. a systemd
196       unit file, a rc script, …)  Otherwise, it’s heavily suggested to
197       create at least a dedicated user.
198     </p>
199     <h3>A dedicated user</h3>
200     <p>
201       Ideally, gmid should be run with root privileges and to drop
202       privileges to a local user.  This way, the created certificates
203       can be readable only by root.  For example, on GNU/linux systems
204       a ‘gmid’ user can be created with:
205     </p>
206     <pre>$ useradd --system --no-create-home -s /bin/nologin -c "gmid Gemini server" gmid</pre>
207     <p>
208       Please consult your OS documentation for more information on the
209       matter.
210     </p>
211     <p>
212       The configuration then needs to be adjusted to include the
213       ‘user’ directive at the top:
214     </p>
215     <pre># /etc/gmid.conf
216 user "gmid"
217 
218 server "example.com" { … }</pre>
219     <p>
220       gmid then needs to be started with root privileges, but will
221       then switch to the provided user automatically.  If by accident
222       the ‘user’ is forgotten and gmid is running as root, it will
223       complain loudly in the logs.
224     </p>
225     <h3>chroot</h3>
226     <p>
227       It’s a common practice for system daemons to chroot themselves
228       into a directory.  From here on I’ll assume /var/gemini, but it
229       can be any directory.
230     </p>
231     <p>
232       A chroot on UNIX-like OS is an operation that changes the
233       “apparent” root directory (i.e. “/”) from the current process
234       and its child.  Think of it like imprisoning a process into a
235       directory and never letting it escape until it terminates.
236     </p>
237     <p>
238       Using a chroot may complicate the use of CGI scripts, because
239       then all the dependencies of the scripts (like sh, perl, or
240       other libraries) needs to be installed inside the chroot too.
241       For this very reason gmid supports FastCGI too.
242     </p>
243     <p>
244       The chroot feature requires a dedicate user, see the previous
245       section.
246     </p>
247     <p>
248       To chroot gmid inside a directory, use the ‘chroot’ directive in
249       the configuration file:
250     </p>
251     <pre># /etc/gmid.conf
252 
253 # the given directory, /var/gemini in this case, must exists.
254 chroot "/var/gemini"</pre>
255     <p>
256       Note that once ‘chroot’ is in place, every ‘root’ directive is
257       implicitly relative to the chroot, but ‘cert’ and ‘key’ aren’t!
258     </p>
259     <p>For example, given the following configuration:</p>
260     <pre># /etc/gmid.conf
261 
262 user "gmid"
263 chroot "/var/gemini"
264 
265 server "example.com" {
266 	cert "/etc/ssl/example.com.pem"
267 	key  "/etc/ssl/example.com.key"
268 	root "/example.com"
269 }</pre>
270     <p>
271       The certificate and the key path are the specified ones, but the
272       root directory of the virtual host is actually
273       “/var/gemini/example.com/”.
274     </p>
275   </body>
276 </html>