# comitium quickstart

comitium is meant to be very easy to get up and running, even in a shared
hosting environment where you don't have root access.  All you need is a Gemini
server capable of hosting static pages and a way to run a program in regular
intervals, such as cron.


## installing

If you can write to `/usr/local/` then you can just follow the instructions
including `make install` on the [README][].  If you only have access to your
home directory, you can instead find the binary and man page in `build/` after
running `make`.  You can then copy or symlink `comitium` to your preferred bin
directory and you can access the man page with `man -l build/comitium.1`.

Prebuilt binraies are also available, but they are x86-64 only and for a limited
number of operating systems, so it is preferable for you to build it yourself,
if possible.

[README]: README.md


## getting set up

### data directory

Once you have the binary all set up, you need figure out where you want your
data directory to be. If you're serving from `~/public_gemini` or something like
that, then just put `export COMITIUM_DATA="~/public_gemini"` in your shell's rc
file and the files will all be set up there.

If you're serving from `/var/gemini` or something similar where the directory is
owned by a user other than your main user, then for security purposes it's
preferable to use the default data directory and symlink `feeds.gmi` and
`subscriptions.gmi` into your directory.  This way you don't have to run
comitium as root, nor do you need to give users inordinate access to other parts
of the system, nor do you need to log into your gemini user every time you want
to add a feed.


### adding feeds

Now you need to add your subscriptions.  If you don't have an existing list of
feeds, then just go `comitium add <url>` whenever you find a new one and you'll
be all set (see [`man comitium`][man] for more details on the `add` command).
You don't need to run `comitium refresh` after adding a new feed, `add`
automatically fetches the new feed and updates your .json and .gmi files with
the new entries.

If you do have an existing list of feeds, it's pretty trivial (for most formats
anyways :P) to write a shell script or similar to parse whatever format they're
currently in and run `comitium add` for each of them.

[man]: comitium.1.scd


### customizing header

You can customize the header of your feed.gmi.  Simply create a file called
`header.gmi` in your data directory (where your `comitium.json`, `feed.gmi`, and
`subscriptions.gmi` are) and put whatever you want in it.  The line linking to
`subscriptions.gmi` and listing the number of subscriptions will be placed after
the contents of `header.gmi`, separated by one newline.

For example, if `header.gmi` contains:

```
# my aggregator
```

then the final `feed.gmi` will contain:

```
# my aggregator

=> subscriptions.gmi Currently aggregating X capsules, gopherholes, and websites.

Generated on ...
```


### refreshing regularly

I just put it in my crontab to refresh on a six hour interval:
```
0 */6 * * * /usr/local/bin/comitium refresh
```

If you set the data directory with an environment variable like mentioned
earlier, make sure to do something like this, because the environment variable
isn't passed to cron:
```
0 */6 * * * /home/somebody/bin/comitium refresh -d /home/somebody/public_gemini
```


And there you go!  You're all set up, now just open up your favorite Gemini
browser, navigate to `feeds.gmi`, and get to surfin'!