aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorAdam Mathes <adam@trenchant.org>2017-02-20 12:03:12 -0800
committerAdam Mathes <adam@trenchant.org>2017-02-20 12:03:12 -0800
commit10c19ee48bd8ed804cc96da73bb77a684d152471 (patch)
treeb2a4c2faeae488236a6dc74e48c14abfada51af8
parent58edb2b02b9605b053fa2d2ab7de17f2b8eb30b4 (diff)
downloadneko-10c19ee48bd8ed804cc96da73bb77a684d152471.tar.gz
neko-10c19ee48bd8ed804cc96da73bb77a684d152471.tar.bz2
neko-10c19ee48bd8ed804cc96da73bb77a684d152471.zip
updated readme
-rw-r--r--README.md109
1 files changed, 56 insertions, 53 deletions
diff --git a/README.md b/README.md
index 9c0afe9..43fceae 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,16 @@
# Neko
-RSS Reader focused on cat ears mode
+Simple self-hosted, single user RSS reader focused on efficiency and simplicity. Written in Go with a simple javascript ui frontend.
*the cat ears are in your mind*
-Personal web based RSS reader thing
-
## Huh?
I decided I didn't like the [old version that was python and mongo](https://github.com/adammathes/neko_v1) so rewrote it. I wanted to learn some Go. So assume the code is bad since I don't know what I'm doing even more so than normal.
-The javascript frontend is still the same, I might rewrite that too since it's old backbone.js code.
+The javascript frontend is still the same, I might rewrite that too since it's old backbone.js code and in the intervening years it looks like nobody uses that anymore.
-This is not very easy to use/setup/or anything. Sorry! Consider it WIP.
+This is not very easy to use/setup/ yet. Sorry! Consider it WIP, pull requests for containers/snaps/etc welcome.
## Features
@@ -23,52 +21,31 @@ This is not very easy to use/setup/or anything. Sorry! Consider it WIP.
* that's all you should ever need
* automatically marks items read in an infinite stream of neve-rending content (until you run out of content and it ends)
-## TODO
-
- * OPML import/export
- * feeds.txt import/export
- * mark all as read
- * proper code comments
-
## Installation
### Prerequesites
-[Install Go -- https:/golang.org](https://golang.org)
+[Go](https://golang.org)
-[Install MySQL](https://dev.mysql.com) or [MariaDB](https://mariadb.com) or some other drop-in replacement.
+[MySQL](https://dev.mysql.com) or a drop-in replacement like [MariaDB](https://mariadb.com)
-Postgresql support is left as an exercise for the reader to implement and send a pull request for.
+PostgreSQL support is left as an exercise for the reader to implement and send a pull request for.
### Set up $GOPATH if one doesn't exist already
$ mkdir $HOME/go
$ export GOPATH=$HOME/go
-### Get neko code
-
- $ go get adammathes.com/neko
-
-### Get dependencies
-
- $ cd $GOPATH/src/adammathes.com/neko
- $ make deps
+See also: [The GOPATH environment variable](https://golang.org/doc/code.html#GOPATH)
-or...
+### Get and build neko
- $ go get [each dependency listed in the handy Makefile you just ignored]
-
-### Build
-
- $ cd $GOPATH/src/github.com/adammathes/neko
- $ go build
- $ go build cmd/nekoweb
- $ go build cmd/nekocrawl
-
-This should create "nekoweb" and "nekocrawl" binaries because command line flags are annoying.
-
-Also there's a Makefile there so a simple "make" should work. Maybe? Makefiles are weird and not really go-ish and not well tested.
+ $ go get adammathes.com/neko
+
+This will download neko code, dependencies, and build them all in $HOME/go/src/
+A `neko` binary should now be in $HOME/go/bin/
+
### Create MySQL table and user
$ mysqladmin -uroot -p create neko
@@ -78,37 +55,63 @@ Also there's a Makefile there so a simple "make" should work. Maybe? Makefiles a
CREATE USER 'neko'@'localhost' identified by 'yourawesomepasswordgoeshere';
GRANT ALL PRIVILEGES ON neko.* TO 'neko'@'localhost';
-### Configuration
+## Configuration
Copy example configuration and edit as needed.
- $ cp config.example config.json
+ $ cp $HOME/go/src/adammathes.com/neko/config.example config.json
-The configuration is JSON which was probably not a good idea. Sorry? It should be straightforward.
+The configuration is JSON which was probably not a good idea.
-### Run web server
+| name | value | example |
+|--------------|--------------------------------------------------|----------------|
+| `db` | mysql database connection string | root:@tcp(127.0.0.1:3306)/neko |
+| `web` | web address/port to bind to | | 127.0.0.0.1:4994 |
+| `username` | username for single user auth | user
+| `password` | plaintext -- will be encrypted in client cookie | notagoodpassword |
+| `static_dir` | absolute path of the static files |/home/user/go/src/adammathes.com/neko/static/|
- $ ./nekoweb config.json
-
-Load URL/port specified in config. Add some feeds! There's an import command that would make this easier but it's wonky (neko addfeed <url>)
-
-### Run Crawler
+### Add Feeds
+
+ $ neko -add http://trenchant.org/rss.xml
+
+Add as many feeds as you'd like to start. You can add more in the web ui later.
+
+Neko will look for a `config.json` in the local directory -- otherwise specify the location with the `-c` flag.
+
+ $ neko -add <url> -c /path/to/config.json
+
+### Crawl Feeds
+
+ $ neko -update
- $ ./nekocrawl config.json
-
This should fetch, download, parse, and store in the database your feeds.
-### Operationalize
+### Run web server
+
+ $ neko -serve
+
+## Running Continuously
-#### Add to cron
+### Crawl Regularly Via Cron
-Place your binaries and config files some place reasonable and add a cron job
+Depending on your binaries/configs something like --
- 34 * * * * ~/bin/nekocrawl ~/neko_config.json &> /dev/null
+ 34 * * * * neko -c /etc/neko.config
-#### Daemonize server
+-- should crawl regularly on the hour in cron.
+
+### Server
Sorry it's 2017 and there are like a bajillion incompatible ways to do this on *nix-alikes and it's ridiculous so I'm probably just going to give up on Linux and use OpenBSD so just run it in tmux or something I guess? I mean, set up an init script with a minimal privileged user. Whatever. UNIX is great, have fun.
-Example NGINX/APACHE proxypass goes here if I ever write it.
+There's an example configuration for systemd + nginx in etc in this repo.
+
+## TODO
+
+ * OPML import/export
+ * feeds.txt import/export
+ * mark all as read cmd
+ * comments/docs
+ * rewrite frontend in a modern js framework