1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
|
<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>
|
