aboutsummaryrefslogblamecommitdiffstats
path: root/readme.html
blob: b47955b33511cff224b018814dc2c78e8898db58 (plain) (tree)
1
2
3
4
5
6
7
8
9
10









                                               













                                                                                                   



                       



                                         
                                           

    



                                                              

    

                                                                

    



                                                                

    


                                                      

    







                                                                                        
 





                                                                         

 

                                                                                                                               





                                                                                                    

                                                                                                                                       

    

                                      



                                           




                                                                                                                                
     

                                                                                                                                             
 
                                                                                       
 




                                                                                                                                               
 
                                                  
 




                                                                                                                                               
 

                                                           
 
                                                                                      

    

                                                                          

     

                                        



                                                                                                                                                                                

                                                                                                                                                 
 


                                                                                                                                                                







                                                                                                                   
                                                                                                                                                             
 

                                    
 




                                                                                                                                                 





                                                                                                                                             
                                                                                                                                                            





                                                                             
                                                                                                                                              


                                               

                                                                                                                                       
 
                                                                          


                                                    

                                                                                                                                             
 
                                                 




                                                                              

                                                                                                                                   
 
                                                                           








                                                                                                                                    

                                                                                                                                                                       






                                                                                
                                                                                                  
 

                                                             
 
                            
 

                                                               
 
                          
 

                                                               
 
                 
 

                                      
 

























                                                                                                                               

    






                                                                     
     









                                                                                                                                                                                                                                                                                                          
 
                                                                                                                                                                           
 









                                                                                                                                       
 

                                                                                                                                                  
<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>



<p><strong>Table of Contents</strong></p>

<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="#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&#39;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&#39;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>There&#39;s no configuration file -- everything is handled with a few command line flags. You shouldn&#39;t need to change the defaults most of the time.</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.</p>

<pre><code>$ neko --database=/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>-d, --database string</p>

<pre><code>    sqlite database file (default &#34;neko.db&#34;)
</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 (default 4994)
</code></pre>

<p>-i, --imageproxy</p>

<pre><code>    rewrite and proxy all image requests for privacy (experimental)
</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>
<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</li>
<li>auto-refresh feeds from web interface</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 &#34;normal&#34; 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&#39;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&#39;t know what I&#39;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&#39;s old backbone.js code but it still seems to mostly work. It&#39;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>