nytpu
99 lines
3.4 KiB
Markdown
99 lines
3.4 KiB
Markdown
# 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
|
|
|
|
Prebuilt binaries are available, see [https://nytpu.com/releases/comitium/](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`.
|
|
|
|
[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'!
|