From 10c19ee48bd8ed804cc96da73bb77a684d152471 Mon Sep 17 00:00:00 2001 From: Adam Mathes Date: Mon, 20 Feb 2017 12:03:12 -0800 Subject: updated readme --- README.md | 109 ++++++++++++++++++++++++++++++++------------------------------ 1 file changed, 56 insertions(+), 53 deletions(-) (limited to 'README.md') 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 ) - -### 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 -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 -- cgit v1.2.3