move quickstart.md to quickstart.en.md

1 files changed, 98 insertions, 0 deletions

diff --git a/doc/quickstart.en.md b/doc/quickstart.en.md
new file mode 100644
index 0000000..d5bf8fd
--- /dev/null
+++ b/doc/quickstart.en.md
@@ -0,0 +1,98 @@
+# 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'!