1 => / Home
2 => /quickstart.gmi Quickstart
3 => /gmid.1.txt docs
4 
5 # gmid quickstart
6 
7 gmid can be run in two different “modes”:
8 
9 * configless: a quick way to serve a directory tree from the shell, useful for testing a capsule before uploading it
10 * daemon mode: gmid reads the configuration file and runs in the background
11 
12 To run gmid in the “configless” mode, just type:
13 
14 ```serve a directory tree from the shell
15 $ gmid path/to/dir
16 ```
17 
18 gmid will then generate a certificate inside ~/.local/share/gmid and serve the given directory locally.
19 
20 ## Setting up a capsule with gmid
21 
22 To host a Gemini capsule you need to run gmid in “daemon” mode.
23 
24 To run gmid in daemon mode a configuration file is needed.  The format of the configuration file is described in the manpage and is quite flexible, but something like the following should be enough to start:
25 
26 ```sample configuration file
27 # /etc/gmid.conf
28 
29 server "example.com" {
30 	cert "/path/to/certificate"
31 	key  "/path/to/private-key"
32 	root "/var/gemini/example.com"
33 }
34 ```
35 
36 You also need to generate a certificate for the capsule.  A X.509 (TLS) certificate can be generated for e.g. with contrib/gencert
37 
38 => https://git.omarpolo.com/gmid/tree/contrib/gencert contrib/gencert
39 
40 ```generate a certificate using contrib/gencert
41 $ ./contrib/gencert example.com
42 Generating a 4096 bit RSA private key
43 .................................................++++
44 ..........++++
45 writing new private key to './example.com.key'
46 -----
47 
48 Generated files:
49         ./example.com.pem : certificate
50         ./example.com.key : private key
51 ```
52 
53 Optionally, move ‘example.com.pem’ and ‘example.com.key’ to another location.
54 
55 Make sure that the ‘cert’ and ‘key’ options in the configuration file points to these files.
56 
57 Then running gmid is as easy as
58 
59 ```running gmid
60 $ gmid -c /etc/gmid.conf
61 ```
62 
63 Congratulations, your capsule is online!
64 
65 
66 ## Securing your gmid installation
67 
68 gmid employs various techniques to prevent the damage caused by bugs, but some steps needs to be done manually.
69 
70 If gmid was installed from your distribution package manager, chance are that it already does all of this and is also providing a service to run gmid automatically (e.g. a systemd unit file, a rc script, …)  Otherwise, it’s heavily suggested to create at least a dedicated user.
71 
72 
73 ### A dedicated user
74 
75 Ideally, gmid should be started as root and drop privileges to a local user.  This way, the certificates can be readable only by root.  For example, on GNU/linux systems a ‘gmid’ user can be created with:
76 
77 ```how to create the gmid user
78 # useradd --system --no-create-home -s /bin/nologin -c "gmid Gemini server" gmid
79 ```
80 
81 Please consult your OS documentation for more information on the matter.
82 
83 The configuration then needs to be adjusted to include the ‘user’ directive at the top:
84 
85 ```how to use the ‘user’ option
86 # /etc/gmid.conf
87 user "gmid"
88 
89 server "example.com" { … }
90 ```
91 
92 gmid then needs to be started with root privileges, but will then switch to the provided user automatically.  If by accident the ‘user’ option is omitted and gmid is running as root, it will complain loudly in the logs.
93 
94 
95 ### chroot
96 
97 It’s a common practice for system daemons to chroot themselves into a directory.  From here on I’ll assume /var/gemini, but it can be any directory.
98 
99 A chroot on UNIX-like OS is an operation that changes the “apparent” root directory (i.e. the “/”) from the current process and its child.  Think of it like imprisoning a process into a directory and never letting it escape until it terminates.
100 
101 Using a chroot may complicate the use of CGI scripts, because then all the dependencies of the scripts (sh, perl, libraries…) need to be installed inside the chroot too.  For this very reason gmid supports FastCGI.
102 
103 The chroot feature requires a dedicate user, see the previous section.
104 
105 To chroot gmid inside a directory, use the ‘chroot’ directive in the configuration file:
106 
107 ```how to use the ‘chroot’ option
108 # /etc/gmid.conf
109 
110 user "gmid"
111 
112 # the given directory, /var/gemini in this case, must exists.
113 chroot "/var/gemini"
114 ```
115 
116 Note that once ‘chroot’ is in place, every ‘root’ directive is implicitly relative to the chroot, but ‘cert’ and ‘key’ aren’t!
117 
118 For example, given the following configuration:
119 
120 ```example configuration using chroot
121 # /etc/gmid.conf
122 
123 user "gmid"
124 chroot "/var/gemini"
125 
126 server "example.com" {
127 	cert "/etc/ssl/example.com.pem"
128 	key  "/etc/ssl/example.com.key"
129 	root "/example.com"
130 }
131 ```
132 
133 The certificate and the key path are the specified ones, but the root directory of the virtual host is actually “/var/gemini/example.com/”.