<html>
<head>
<meta charset="utf-8">
<style>
pre { font-family: menlo, courier, monospace; }
article { padding: 30px; }
</style>
</head>
<body>
<article><pre>
██
██
██
██░████ ░████▒ ██ ▓██▒ ░████░
███████▓ ░██████▒ ██ ▓██▒ ░██████░
███ ▒██ ██▒ ▒██ ██▒██▒ ███ ███
██ ██ ████████ ████▓ ██░ ░██
██ ██ ████████ █████ ██ ██
██ ██ ██ ██░███ ██░ ░██
██ ██ ███░ ▒█ ██ ██▒ ███ ███
██ ██ ░███████ ██ ▒██ ░██████░
██ ██ ░█████▒ ██ ███ ░████░
v0.2 manual
7/4/2018
</pre>
<ul>
<li><a href="#neko" rel="nofollow">Neko</a>
<ul>
<li><a href="#features" rel="nofollow">Features</a></li>
<li><a href="#screenshots" rel="nofollow">Screenshots</a></li>
</ul></li>
<li><a href="#installation" rel="nofollow">Installation</a>
<ul>
<li><a href="#requirements" rel="nofollow">Requirements</a></li>
<li><a href="#building" rel="nofollow">Building</a>
<ul>
<li><a href="#dependencies" rel="nofollow">Dependencies</a></li>
</ul></li>
</ul></li>
<li><a href="#configuration" rel="nofollow">Configuration</a>
<ul>
<li><a href="#storage" rel="nofollow">Storage</a></li>
</ul></li>
<li><a href="#usage" rel="nofollow">Usage</a>
<ul>
<li><a href="#web-interface" rel="nofollow">Web Interface</a></li>
<li><a href="#add-feed" rel="nofollow">Add Feed</a></li>
<li><a href="#crawl-feeds" rel="nofollow">Crawl Feeds</a></li>
<li><a href="#export" rel="nofollow">Export</a></li>
</ul></li>
<li><a href="#all-command-line-options" rel="nofollow">All Command Line Options</a></li>
<li><a href="#configuration-file" rel="nofollow">Configuration File</a></li>
<li><a href="#todo" rel="nofollow">TODO</a></li>
<li><a href="#history" rel="nofollow">History</a>
<ul>
<li><a href="#early-2017" rel="nofollow">Early 2017</a></li>
<li><a href="#july-2018----v02" rel="nofollow">July 2018 -- v0.2</a></li>
</ul></li>
<li><a href="#feedback" rel="nofollow">Feedback</a></li>
</ul>
<h1><a name="neko" class="anchor" href="#neko" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
Neko</h1>
<p><code>neko</code> is a self-hosted, rss reader focused on simplicity and efficiency.</p>
<p>Backend is written in <code>Go</code> and there is a simple javascript frontend and cat ears.</p>
<p><em>note: the cat ears are in your mind</em></p>
<h2><a name="features" class="anchor" href="#features" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
Features</h2>
<ul>
<li>limited features (#1 feature)</li>
<li>keyboard shortcuts
<ul>
<li><strong>j</strong> - next item</li>
<li><strong>k</strong> - previous item</li>
<li>that's all you should ever need</li>
</ul></li>
<li>automatically marks items read in an infinite stream of never-ending content (until you run out of content and it ends)</li>
<li>full text search</li>
<li>scrapes full text of pages on demand</li>
</ul>
<h2><a name="screenshots" class="anchor" href="#screenshots" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
Screenshots</h2>
<p><img src="screenshot/neko.jpg?raw=true" alt="Screenshot 1" title="Screenshot 1"></p>
<p><img src="screenshot/neko2.jpg?raw=true" alt="Screenshot 2" title="Screenshot 2"></p>
<h1><a name="installation" class="anchor" href="#installation" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
Installation</h1>
<h2><a name="requirements" class="anchor" href="#requirements" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
Requirements</h2>
<p>If you are using a binary, no dependencies!</p>
<p>NOTE: I haven't put up any binaries yet.</p>
<h2><a name="building" class="anchor" href="#building" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
Building</h2>
<h3><a name="dependencies" class="anchor" href="#dependencies" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
Dependencies</h3>
<ul>
<li><a href="https://golang.org" rel="nofollow">Go</a></li>
<li><p><a href="https://github.com/mattn/go-sqlite3" rel="nofollow">go-sqlite3</a></p>
<ul>
<li><a href="https://sqlite.org/index.html" rel="nofollow">sqlite</a></li>
<li><a href="https://gcc.gnu.org" rel="nofollow">gcc</a></li>
</ul>
<p>$ go get adammathes.com/neko</p></li>
</ul>
<p>This will download <code>neko</code>, dependencies, and build them all in <code>$GOPATH/src/</code>. By default this should be something like <code>$HOME/go/src/</code>.</p>
<p>A <code>neko</code> binary should now be in <code>$GOPATH/bin/</code>. By default this is usually <code>$HOME/go/bin/</code></p>
<h1><a name="configuration" class="anchor" href="#configuration" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
Configuration</h1>
<p>Everything can handled with a few command line flags. You shouldn't need to change the defaults most of the time.</p>
<p>You can also set options using a configuration file <a href="http://yaml.org" rel="nofollow"><code>yaml</code></a>, described at the end of this README (but you probably don't need to.)</p>
<h2><a name="storage" class="anchor" href="#storage" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
Storage</h2>
<p>By default <code>neko</code> will create the file <code>neko.db</code> in the current directory for storage.</p>
<p>You can override the location of this database file with the <code>--database</code> command line option or <code>-d</code> short option.</p>
<pre><code>$ neko --database=/var/db/neko.db --add=http://trenchant.org/rss.xml
</code></pre>
<p>which is equivalent to --</p>
<pre><code>$ neko -d /var/db/neko.db --add=http://trenchant.org/rss.xml
</code></pre>
<p>For expert users -- this is a <a href="https://sqlite.org/" rel="nofollow">SQLite</a> database and can be manipulated with standard sqlite commands --</p>
<pre><code>$ sqlite3 neko.db .schema
</code></pre>
<p>-- will print out the database schema.</p>
<h1><a name="usage" class="anchor" href="#usage" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
Usage</h1>
<h2><a name="web-interface" class="anchor" href="#web-interface" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
Web Interface</h2>
<p>You can do most of what you need to do with <code>neko</code> from the web interface, which is what <code>neko</code> does by default.</p>
<pre><code>$ neko
</code></pre>
<p><code>neko</code> web interface should now be available at <code>127.0.0.1:4994</code> -- opening a browser up to that should show you the interface.</p>
<p>You can specify a different port using the <code>--http</code> option.</p>
<pre><code>$ neko --http=9001
</code></pre>
<p>If you are hosting on a publicly available server instead of a personal computer, you can protect the interface with a password flag --</p>
<pre><code>$ neko --password=rssisveryimportant
</code></pre>
<h2><a name="add-feed" class="anchor" href="#add-feed" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
Add Feed</h2>
<p>You can add feeds directly from the command line for convenience --</p>
<pre><code>$ neko --add=http://trenchant.org/rss.xml
</code></pre>
<h2><a name="crawl-feeds" class="anchor" href="#crawl-feeds" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
Crawl Feeds</h2>
<p>Update feeds from the command line with --</p>
<pre><code>$ neko --update
</code></pre>
<p>This will fetch, download, parse, and store in the database your feeds.</p>
<h2><a name="export" class="anchor" href="#export" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
Export</h2>
<p>Export de facto RSS feed standard OPML from the command line with --</p>
<pre><code>$ neko --export=opml
</code></pre>
<p>Change <code>opml</code> to <code>text</code> for a simple list of feed URLs, or <code>json</code> for JSON formatted output.</p>
<p>Export is also available in the web interface.</p>
<p>Import of OPML and other things is a TODO item.</p>
<h1><a name="all-command-line-options" class="anchor" href="#all-command-line-options" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
All Command Line Options</h1>
<p>View all command line options with <code>-h</code> or <code>--help</code></p>
<pre><code>$ neko -h
</code></pre>
<p>Usage of neko:
-a, --add <a href="http://example.com/rss.xml" rel="nofollow">http://example.com/rss.xml</a></p>
<pre><code> add the feed at URL http://example.com/rss.xml
</code></pre>
<p>-c, --config string</p>
<pre><code> read configuration from file
</code></pre>
<p>-d, --database string</p>
<pre><code> sqlite database file
</code></pre>
<p>-x, --export string</p>
<pre><code> export feed. format required: text, json or opml
</code></pre>
<p>-h, --help</p>
<pre><code> print usage information
</code></pre>
<p>-s, --http int</p>
<pre><code> HTTP port to serve on
</code></pre>
<p>-i, --imageproxy</p>
<pre><code> rewrite and proxy all image requests for privacy (experimental)
</code></pre>
<p>-m, --minutes int</p>
<pre><code> minutes between crawling feeds
</code></pre>
<p>-p, --password string</p>
<pre><code> password to access web interface
</code></pre>
<p>-u, --update</p>
<pre><code> fetch feeds and store new items
</code></pre>
<p>-v, --verbose</p>
<pre><code> verbose output
</code></pre>
<p>These are POSIX style flags so --</p>
<pre><code>$ neko --minutes=120
</code></pre>
<p>is equivalent to</p>
<pre><code>$ neko -m 120
</code></pre>
<h1><a name="configuration-file" class="anchor" href="#configuration-file" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
Configuration File</h1>
<p>For convenience, you can specify options in a configuration file.</p>
<pre><code>$ neko -c /etc/neko.conf
</code></pre>
<p>A subset of the command line options are supported in the configuration file, with the same semantics --</p>
<ul>
<li>database</li>
<li>http</li>
<li>imageproxy</li>
<li>minutes</li>
<li>password</li>
</ul>
<p>For example --</p>
<pre><code>database: /var/db/neko.db
http: 9001
imageproxy: true
minutes: 90
password: VeryLongRandomStringBecauseSecurityIsFun
</code></pre>
<h1><a name="todo" class="anchor" href="#todo" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
TODO</h1>
<ul>
<li>manually initiate crawl/refresh from web interface (done: /crawl/)</li>
<li>auto-refresh feeds from web interface (wip: but may not be working right)</li>
<li>import</li>
<li>mark all as read</li>
<li>rewrite frontend in a modern js framework</li>
<li>prettify interface</li>
<li>cross-compilation of binaries for "normal" platforms</li>
</ul>
<h1><a name="history" class="anchor" href="#history" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
History</h1>
<h2><a name="early-2017" class="anchor" href="#early-2017" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
Early 2017</h2>
<p>I decided I didn't like the <a href="https://github.com/adammathes/neko_v1" rel="nofollow">original version of this that was python and mongo</a> so rewrote it. I wanted to learn some Go. So assume the code is not great since I don't know what I'm doing even more so than normal.</p>
<p>The Javascript frontend is still the same, I keep saying I will rewrite that too since it's old backbone.js code but it still seems to mostly work. It's not very pretty though.</p>
<h2><a name="july-2018-v0-2" class="anchor" href="#july-2018-v0-2" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
July 2018 -- v0.2</h2>
<p>Significant changes to simplify setup, configuration, usage. The goal was typing <code>neko</code> should be all you need to do to get started and use the software.</p>
<ul>
<li>removed MySQL requirement (eliminating a ton of configuration and complexity)</li>
<li>added SQLite support (easier!)</li>
<li>auto-initialization of database file with embedded schema</li>
<li>removed json-formatted config file -- all options are command line options</li>
<li><code>neko</code> runs web server by default</li>
<li><code>neko</code> server crawls feeds regularly rather than requiring cron</li>
</ul>
<h1><a name="feedback" class="anchor" href="#feedback" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
Feedback</h1>
<p>Pull requests and issues are welcomed at <a href="https://github.com/adammathes/neko" rel="nofollow">https://github.com/adammathes/neko</a></p>
</article></body></html>
