about summary refs log tree commit diff
path: root/README.md
blob: 05fa7508068a3dbf8475847f4f2fd6661fc5b5ef (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
# spacecookie

Haskell gopher server daemon and library.

## Features

* implements RFC1436
* optionally supports common protocol extensions:
  * informational entries via the `i`-type
  * [`h`-type and URL entries](http://gopher.quux.org:70/Archives/Mailing%20Lists/gopher/gopher.2002-02%7C/MBOX-MESSAGE/34)
* supports gophermaps (see [below](#adding-content))
* supports systemd socket activation
* provides a library for custom gopher applications ([see documentation](http://hackage.haskell.org/package/spacecookie/docs/Network-Gopher.html))

## Non-Features

spacecookie intentionally does not support:

* HTTP, Gemini: Multi protocol support is a non-goal for spacecookie.
  For HTTP you can [proxy](https://github.com/sternenseemann/gopher-proxy)
  pretty easily, however.
* Search: Gopher supports search transactions, but the spacecookie daemon doesn't offer
  the possibility to add a search engine to a gopherspace. It is however
  entirely possible to implement an index search server using [the
  spacecookie library](https://hackage.haskell.org/package/spacecookie/docs/Network-Gopher.html)

## Installation

* Nix(OS): [`pkgs.haskellPackages.spacecookie`](https://search.nixos.org/packages?channel=unstable&from=0&size=50&sort=relevance&query=spacecookie)
  (see also [below](#on-nixos))
* Cabal: `cabal v2-install spacecookie`
  (see also [hackage package](http://hackage.haskell.org/package/spacecookie))

## Documentation

* User Documentation: [spacecookie(1)](https://sternenseemann.github.io/spacecookie/spacecookie.1.html)
* [Developer Documentation](https://hackage.haskell.org/package/spacecookie)

## Configuration

spacecookie is configured via a JSON configuration file.
All available options are documented in
[spacecookie.json(5)](https://sternenseemann.github.io/spacecookie/spacecookie.json.5.html).
This repository also contains an example configuration file in
[`etc/spacecookie.json`](./etc/spacecookie.json).

## Running

After you've created your config file just start spacecookie like this:

	spacecookie /path/to/spacecookie.json

spacecookie runs as a simple process and doesn't fork or write a PID file.
Therefore any supervisor (systemd, daemontools, ...) can be used to run
it as a daemon.

### With systemd

spacecookie supports systemd socket activation. To set it up you'll need
to install `spacecookie.service` and `spacecookie.socket` like so:

	cp ./etc/spacecookie.{service,socket} /etc/systemd/system/
	systemctl daemon-reload
	systemctl enable spacecookie.socket
	systemctl start  spacecookie.socket
	systemctl start  spacecookie.service # optional, started by the socket automatically if needed

Of course make sure that all the used paths are correct!

How the systemd integration works is explained in
[spacecookie(1)](https://sternenseemann.github.io/spacecookie/spacecookie.1.html#SYSTEMD_INTEGRATION).

### On NixOS

[NixOS](https://nixos.org/nixos/) provides a service module for spacecookie:
[`services.spacecookie`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/spacecookie.nix).
Setting up spacecookie is as simple as adding the following line to your `configuration.nix`:

	services.spacecookie.enable = true;

For all available options, refer to the NixOS manual:

* [NixOS stable](https://nixos.org/manual/nixos/stable/options.html#opt-services.spacecookie.enable)
* [NixOS unstable](https://nixos.org/manual/nixos/unstable/options.html#opt-services.spacecookie.enable)

## Adding Content

spacecookie acts as a simple file server, only excluding files
or directories that start with a dot. It generates gopher menus
automatically, but you can also use custom ones by adding a
gophermap file.

spacecookie checks for `.gophermap` in every directory it serves and,
if present, uses the menu specified in there.

Such a file looks like this:

	You can just start writing text that
	will be displayed by the gopher client
	without a link to a file. Empty lines are
	also possible.

	1Menu Entry for a directory full of funny stuff	/funny
	IFunny Image	/funny.jpg
	gcat gif	/cat.gif
	0about me	/about.txt
	1Floodgap's gopher server	/	gopher.floodgap.com	70

As you can see, it largely works like the actual gopher menu a server will
send to clients, but allows to omit redundant information and to insert
lines that are purely informational and not associated with a file.
[spacecookie.gophermap(5)](https://sternenseemann.github.io/spacecookie/spacecookie.gophermap.5.html)
explains syntax and semantics in more detail.

The format is compatible with the ones supported by
[Bucktooth](gopher://gopher.floodgap.com/1/buck/) and
[pygopherd](https://github.com/jgoerzen/pygopherd).
If you notice any incompatibilities, please open an issue.

## Portability

spacecookie is regularly tested on GNU/Linux via CI, but
should also work on other Unix-like operating systems.
Most portability problems arise due to
[haskell-socket](https://github.com/lpeterse/haskell-socket)
which is for example known
[not to work on OpenBSD](https://github.com/lpeterse/haskell-socket/issues/63).

Windows support would be possible, but could be tricky as gopher
expects Unix-style directory separators in paths. I personally
don't want to invest time into it, but would accept patches adding
Windows support.