molniya/README.md

molniya - Gemini orbit software

An orbit is like a webring but for gemini. This code was originally written to service LEO[1], the first (to my knowledge) orbit ever made.

A Molniya orbit is a type of satellite orbit designed to provide communications and remote sensing coverage over high latitudes (thanks Wikipedia[2]). It was invented by the Russians for their spy satellites. I feel like it's a fitting name.

1]: gemini://tilde.team/~khuxkm/leo/
\[2]: https://en.wikipedia.org/wiki/Molniya_orbit

## How to use Molniya

In order to use Molniya, do the following:

1. Clone this repository into a place on your Gemini root directory. (If you're using a userdir for this, that's fine too.)

2. Modify `config.py`. Namely, update `MAIN_PAGE` to be the link to the index.gmi file, and update `REQUIRED_LINKS` to be the links to `next.cgi`, `prev.cgi`, and `rand.cgi`, wherever they are accessible via Gemini. `BACKLINKS` and `determine_capsule` shouldn't need to be changed (unless GUS is down or you want to change how Zenit decides what makes up a capsule.

3. Modify `index.gmi` to link to your files instead of mine. Also, update the email to an email people can reach you at if they need you to manually add/remove them from your orbit.

4. Get people to link to your main page and one of `next.cgi`, `prev.cgi`, and `rand.cgi`.

5. Set a cronjob to run Zenit every now and again. (~~If I knew how often GUS indexed, I'd give a specific frequency, but I don't, so I won't.~~ Currently about weekly, shouldn't be more than daily, so I'd set a cronjob to run every week or so. Remember you can always manually run Zenit. See [#1](https://tildegit.org/khuxkm/molniya/issues/1).)

## What is the orbit.json file?

The `orbit.json` file contains all of the URLs in the orbit. It's how Molniya and Zenit know what URLs are there, and in what order.

## You keep mentioning Zenit. What is it?

Zenit is the Molniya indexer. It uses GUS's backlinks feature to get a list of pages that link to the orbit, and then checks them for having a link to allow people to continue to traverse the orbit.

## Can you add links to orbit.json manually?

Of course you can! Just make sure to keep `orbit.json` valid JSON, or it'll break the Molniya library and the entire orbit will break.

You don't even need Zenit for a private orbit; just manually add the URLs of your friends' pages to `orbit.json` and it'll Just Work(tm).

## Why does Molniya want the next and previous links to contain the URL of the page as a query?

Because Gemini lacks referrers (a good choice), there's no way to tell where a client came from just by studying the request. As such, it needs some way of indicating where in the orbit the client is.

`rand.cgi` lacks this requirement because it just gets a random page anyways. That being said, it's best if the client also puts their URL in the `rand.cgi` link, just so that users selecting the random link option aren't sent back to the very site they just came from.

## Why does Molniya abuse redirects to send the user on to the next page? Why not have a landing page?

Because I don't feel like implementing a landing page to just have the user click off of it. The redirect *should* replace the orbit link in the client's history, so the user shouldn't be adversely affected by this.