1 # gmid quickstart guide
2 
3 gmid can be run in two different “modes”:
4 
5 * configless: a quick way to serve a directory tree from the shell, useful for testing a capsule before uploading it
6 * daemon mode: gmid reads the configuration file and runs in the background
7 
8 To run gmid in the “configless” mode, just type:
9 
10 ```serve a directory tree from the shell
11 $ gmid path/to/dir
12 ```
13 
14 gmid will then generate a certificate inside ~/.local/share/gmid and serve the given directory locally.
15 
16 ## Setting up a capsule with gmid
17 
18 To host a Gemini capsule you need to run gmid in “daemon” mode, and so 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:
19 
20 ```sample configuration file
21 # /etc/gmid.conf
22 
23 server "example.com" {
24 	cert "/etc/ssl/example.com.pem"
25 	key  "/etc/ssl/private/example.com.key"
26 
27 	# path to the root directory of your capsule
28 	root "/var/gemini/example.com"
29 }
30 ```
31 
32 A certificate is needed for the capsule.  Generate one for e.g. using contrib/gencert:
33 
34 => https://git.omarpolo.com/gmid/tree/contrib/gencert contrib/gencert
35 
36 ```generate a certificate using contrib/gencert
37 $ ./contrib/gencert example.com
38 Generating a 4096 bit RSA private key
39 .................................................++++
40 ..........++++
41 writing new private key to './example.com.key'
42 -----
43 
44 Generated files:
45         ./example.com.pem : certificate
46         ./example.com.key : private key
47 ```
48 
49 Move ‘example.com.pem’ and ‘example.com.key’ to a safe place and double check that the ‘cert’ and ‘key’ options in the configuration points to these files.
50 
51 For example, save them in ‘/etc/ssl/’ (as root)
52 
53 ```how to save the certificate and private key in /etc/ssl
54 # mkdir -p /etc/ssl/private
55 # chown 700 /etc/ssl/private
56 # mv example.com.pem /etc/ssl/
57 # mv example.com.key /etc/ssl/private/
58 ```
59 
60 Then running gmid is as easy as
61 
62 ```running gmid
63 $ gmid -c /etc/gmid.conf
64 ```
65 
66 Congratulations, your capsule is online!
67 
68 
69 ## Securing your gmid installation
70 
71 gmid employs various techniques to prevent the damage caused by bugs, but some steps needs to be done manually.
72 
73 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 rc script, a systemd unit file, …)  Otherwise, it’s heavily suggested to create at least a dedicated user.
74 
75 
76 ### A dedicated user
77 
78 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:
79 
80 ```how to create the gmid user
81 # useradd --system --no-create-home -s /bin/nologin -c "gmid Gemini server" gmid
82 ```
83 
84 If you use systemd-sysusers:
85 
86 ```how to create the gmid user, using systemd-sysusers
87 # systemd-sysusers contrib/gmid.sysusers
88 ```
89 
90 Please consult your OS documentation for more information on the matter.
91 
92 The configuration then needs to be adjusted to include the ‘user’ directive at the top:
93 
94 ```how to use the ‘user’ option
95 # /etc/gmid.conf
96 user "gmid"
97 
98 server "example.com" { … }
99 ```
100 
101 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.
102 
103 
104 ### chroot
105 
106 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.
107 
108 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.
109 
110 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.
111 
112 The chroot feature requires a dedicate user, see the previous section.
113 
114 To chroot gmid inside a directory, use the ‘chroot’ directive in the configuration file:
115 
116 ```how to use the ‘chroot’ option
117 # /etc/gmid.conf
118 
119 user "gmid"
120 
121 # the given directory, /var/gemini in this case, must exists.
122 chroot "/var/gemini"
123 ```
124 
125 Note that once ‘chroot’ is in place, every ‘root’ directive is implicitly relative to the chroot, but ‘cert’ and ‘key’ aren’t!
126 
127 For example, given the following configuration:
128 
129 ```example configuration using chroot
130 # /etc/gmid.conf
131 
132 user "gmid"
133 chroot "/var/gemini"
134 
135 server "example.com" {
136 	cert "/etc/ssl/example.com.pem"
137 	key  "/etc/ssl/example.com.key"
138 	root "/example.com"
139 }
140 ```
141 
142 The certificate and the key path are the specified ones, but the root directory of the virtual host is actually “/var/gemini/example.com/”.