aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
blob: 0d084df7c1be16e3c92bf4996de67d21769bb6ae (plain) (blame)
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
# Neko

`neko` is a self-hosted, rss reader focused on simplicity and efficiency.

Backend is written in `Go` and there is a simple javascript frontend and cat ears.

*the cat ears are in your mind*

## 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 and in the intervening years it looks like nobody uses that anymore.

This is not very easy to use/setup/ yet. Sorry! Consider it WIP, pull requests for containers/snaps/etc welcome.

## Features

   * limited features (#1 feature)
   * keyboard shortcuts
      * **j** - next item
      * **k** - previous item
      * that's all you should ever need
   * automatically marks items read in an infinite stream of never-ending content (until you run out of content and it ends)
   
## Installation

### Prerequesites 

   * [Go](https://golang.org)
   * Persistence layer via one of either
     * [SQLite](https://sqlite.org/) (newly supported and easiest to setup)
     * [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.

### Set up $GOPATH if one doesn't exist already

    $ mkdir $HOME/go  
    $ export GOPATH=$HOME/go
    
See also: [The GOPATH environment variable](https://golang.org/doc/code.html#GOPATH)

### Get and build neko

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

### Database Setup

#### SQLite

Initialize a new SQLite database file with `sqlite.init.sql`

    $ cat sqlite.init.sql | sqlite3 neko.db

#### Create MySQL table and user

If you are using MySQL or equivalent --

    $ mysqladmin -uroot -p create neko  
    $ mysql -uroot -p neko < init.sql  
    $ echo "probably a good idea to make a limited privilege user"  
    $ mysql -uroot -p neko  
    CREATE USER 'neko'@'localhost' identified by 'yourawesomepasswordgoeshere';  
    GRANT ALL PRIVILEGES ON neko.* TO 'neko'@'localhost';  
    
Initialize the tables with --

    $ cat init.mysql.sql | mysql neko

## Configuration 

Copy example configuration and edit as needed.

    $ cp $HOME/go/src/adammathes.com/neko/config.example config.json

The configuration is JSON which was probably not a good idea.

| name         | value                                            | example        |
|--------------|--------------------------------------------------|----------------|
| `db_driver`  | database driver - sqlite3 or mysql               | sqlite3 |
| `db`         | mysql connection string OR sqlite file           | 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/|


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

This should fetch, download, parse, and store in the database your feeds.

### Run web server

    $ neko --serve
    
UI should now be available at the address in your `web` configuration setting.
 
## Operationalize

### Crawl Regularly Via Cron

Depending on your binaries/configs something like --

    34 * * * * neko -c /etc/neko.config -u

-- should crawl regularly on the hour in cron.

### Server as Daemon

There's an example configuration for systemd in etc in this repo that should work for modern Linux systems on systemd.

## Import/Export

Import is a TODO

Export de facto RSS feed standard OPML from the command line with --

    $ neko --export opml

Change `opml` to `text` for a simple list of feed URLs, or `json` for JSON formatted output.


## TODO

   * automate database initializtion
   * embed templates / static files into binary
   * feed / item import
   * mark all as read command
   * rewrite frontend in a modern js framework
   * less ugly frontend