From 1f0035d0a5d3b5482b7b3fd63fe681e6acae5e6e Mon Sep 17 00:00:00 2001 From: nytpu Date: Tue, 11 May 2021 13:20:19 -0600 Subject: move quickstart.md to quickstart.en.md --- doc/quickstart.en.md | 98 ++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/quickstart.md | 98 ---------------------------------------------------- 2 files changed, 98 insertions(+), 98 deletions(-) create mode 100644 doc/quickstart.en.md delete mode 100644 doc/quickstart.md (limited to 'doc') 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 ` 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'! diff --git a/doc/quickstart.md b/doc/quickstart.md deleted file mode 100644 index 31208d4..0000000 --- a/doc/quickstart.md +++ /dev/null @@ -1,98 +0,0 @@ -# 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 ` 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'! -- cgit v1.2.3