rdelaage/gmid
1
0
Fork 0
mirror of https://github.com/omar-polo/gmid.git synced 2024-09-27 21:11:51 +02:00
Code Issues Packages Projects Releases Wiki Activity

tweak the quickstart guide

Browse Source
This commit is contained in:
Omar Polo 2021-10-11 15:46:41 +00:00
parent c0f81ed39e
commit fc4b58d450
2 changed files with 32 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
site/quickstart.gmi
View File

@ -13,7 +13,11 @@ $ gmid path/to/dir
gmid will then generate a certificate inside ~/.local/share/gmid and serve the given directory locally.
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 for simple setup something like the following should be enough:
## Setting up a capsule with gmid
To host a Gemini capsule you need to run gmid in “daemon” mode.
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:
```sample configuration file
# /etc/gmid.conf
@ -25,7 +29,7 @@ server "example.com" {
}
```
A X.509 (TLS) certificate can be generated using contrib/gencert
You also need to generate a certificate for the capsule. A X.509 (TLS) certificate can be generated for e.g. with contrib/gencert
=> https://git.omarpolo.com/gmid/tree/contrib/gencert contrib/gencert
@ -52,6 +56,8 @@ Then running gmid is as easy as
$ gmid -c /etc/gmid.conf
```
Congratulations, your capsule is online!
## Securing your gmid installation
@ -62,7 +68,7 @@ If gmid was installed from your distribution package manager, chance are that it
### A dedicated user
Ideally, gmid should be started with root privileges and drop privileges to a local user. This way, the created certificates can be readable only by root. For example, on GNU/linux systems a ‘gmid’ user can be created with:
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:
```how to create the gmid user
# useradd --system --no-create-home -s /bin/nologin -c "gmid Gemini server" gmid
@ -79,16 +85,16 @@ user "gmid"
server "example.com" { … }
```
gmid then needs to be started with root privileges, but will then switch to the provided user automatically. If by accident the ‘user’ is forgotten and gmid is running as root, it will complain loudly in the logs.
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.
### chroot
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.
A chroot on UNIX-like OS is an operation that changes the “apparent” root directory (i.e. “/”) 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.
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.
Using a chroot may complicate the use of CGI scripts, because then all the dependencies of the scripts (like sh, perl, libraries…) need to be installed inside the chroot too. For this very reason gmid supports FastCGI.
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.
The chroot feature requires a dedicate user, see the previous section.

35
site/quickstart.html
View File

@ -147,11 +147,13 @@
gmid will then generate a certificate inside ~/.local/share/gmid
and serve the given directory locally.
</p>
<h2>Setting up a capsule with gmid</h2>
<p>To host a Gemini capsule you need to run gmid in “daemon” mode.</p>
<p>
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 for simple setup something like the
following should be enough:
is quite flexible, but something like the following should be
enough to start:
</p>
<pre># /etc/gmid.conf
@ -161,7 +163,8 @@ server "example.com" {
root "/var/gemini/example.com"
}</pre>
<p>
A X.509 (TLS) certificate can be generated using
You also need to generate a certificate for the capsule. A
X.509 (TLS) certificate can be generated for e.g. with
<a href="https://git.omarpolo.com/gmid/tree/contrib/gencert">contrib/gencert</a>:
</p>
<pre>$ ./contrib/gencert example.com
@ -184,6 +187,7 @@ Generated files:
</p>
<p>Then running gmid is as easy as</p>
<pre>$ gmid -c /etc/gmid.conf</pre>
<p>Congratulations, your capsule is online!</p>
<h2>Securing your gmid installation</h2>
<p>
gmid employs various techniques to prevent the damage caused by
@ -198,10 +202,10 @@ Generated files:
</p>
<h3>A dedicated user</h3>
<p>
Ideally, gmid should be started with root privileges and drop
privileges to a local user. This way, the created certificates
can be readable only by root. For example, on GNU/linux systems
a ‘gmid’ user can be created with:
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:
</p>
<pre># useradd --system --no-create-home -s /bin/nologin -c "gmid Gemini server" gmid</pre>
<p>
@ -219,8 +223,8 @@ server "example.com" { … }</pre>
<p>
gmid then needs to be started with root privileges, but will
then switch to the provided user automatically. If by accident
the ‘user’ is forgotten and gmid is running as root, it will
complain loudly in the logs.
the ‘user’ option is omitted and gmid is running as root, it
will complain loudly in the logs.
</p>
<h3>chroot</h3>
<p>
@ -230,15 +234,16 @@ server "example.com" { … }</pre>
</p>
<p>
A chroot on UNIX-like OS is an operation that changes the
“apparent” root directory (i.e. “/”) 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.
“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.
</p>
<p>
Using a chroot may complicate the use of CGI scripts, because
then all the dependencies of the scripts (like sh, perl,
libraries…) need to be installed inside the chroot too. For
this very reason gmid supports FastCGI.
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.
</p>
<p>
The chroot feature requires a dedicate user, see the previous