This document is also available in:

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.


Prebuilt binaries are available, see https://nytpu.com/releases/comitium/

If you want to build yourself:
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.

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 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.

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'!