Update docs.
[webvac] / README
1 This is a somewhat specialized chunk of code!
2
3 Using a lookup table in Redis and venti as the backing storage, webvac
4 serves static content.  It comes with utility `webvac-sweep`, that
5 pushes content into venti, optionally removing it from the filesystem.
6 The `webvac-server` program itself starts up a webserver.  Give these
7 programs '-h' or '--help' to see helpful(?) information, and see below
8 for configuration.
9
10 Currently I am only using it to serve uploads for UGC in some small- to
11 moderately high-traffic Pleroma instances.  I have been using venti to
12 do incremental backups of the data (replication is speedy), and since
13 the uploads are WORM ("write once, read many") data, I thought it'd be
14 cool to serve the data directly out of venti.  It worked better than
15 expected!
16
17 I expect to use this more often and thus expect it to become a bit more
18 general as a result, but for right now, it makes a couple of assumptions
19 about where it serves files.
20
21 = Quick Start
22
23   [Check that your venti and Redis servers are operational.]
24   $ sudo ed /etc/webvac.json
25   a
26   {"server_path_prepend":"/where/uploads/get/put/in/the/filesystem"}
27   .
28   wq
29   $ sudo $EDITOR /etc/nginx/whatever
30   [edit your nginx configuration to proxy requests for files to localhost:8891
31   if the file doesn't exist]
32   $ webvac-server -D
33   $ find /where/uploads/get/put/in/the/filesystem -type f -print0 |
34    xargs -0 -n30 -P8 webvac-sweep -v -- 
35   [At this point, you should be able to rm the files in server_path_prepend
36   to start serving them out of venti.  Big ones are slow for now.]
37
38 = Mise en place
39
40 You will need a venti server and a Redis server.  It'll work fine with
41 either Plan 9 venti or P9P venti.  You will also need the 'vac' and
42 'unvac' utilities that come with P9P.
43
44 You will need to either have all the stuff in the default places, or
45 you'll need to configure a handful of things.  Otherwise, you will need
46 to configure probably one thing.
47
48 = Overhead
49
50 Just empirically, for about 100GB of files, venti takes 86GB of disk (no
51 surprise, since it's mostly JPGs and MP4s, so it's already compressed;
52 the savings are probably from dedup), and Redis takes about 60MB of RAM
53 for this.  All of the files were put into venti as part of the backup
54 solution.  CPU overhead is negligible, the server takes about 200MB of
55 RAM for both workers.
56
57 = Installation
58
59 `gem install webvac` should do it.
60
61 = Configuration
62
63 The nginx config I used to test is in doc/examples.
64
65 You will need to create a JSON file that specifies the configuration.
66 The first readable file from the following list is used:
67
68 * The filename given in the $WEBVAC_CONFIG environment variable.
69 * ./config/webvac.json
70 * $HOME/.webvac.json
71 * /etc/webvac.json
72
73 Here is an annotated list of configuration options, all of which start
74 with their default values.  You will almost certainly need to change
75 server_path_prepend.
76
77   {
78     // A Redis connection string, one that Redic will take:
79     "redis_url": "redis://localhost:6379/0",
80
81     // These two options are used to turn the request path into a filesystem
82     // path.  Watch this space, I might turn server_path_strip into an array.
83
84     // The beginning of the path that the entire server sits under; that is,
85     // what should be stripped from the front of the path.  For Pleroma, users'
86     // uploads are all under /media, so this works if you're serving uploads from
87     // https://$domain/media/$file .  You should probably not change this one for
88     // now, as Rake routes depend on it.
89     "server_path_strip": "/media",
90     // The beginning of the path in the *filesystem* that corresponds to where
91     // the files are kept.  It is *incredibly* unlikely that you are using the
92     // same path I am.
93     "server_path_prepend": "/media/block/fse",
94
95     // This is where the venti server is.  (This might be an array at some
96     // point.)  This address is in dial(2) syntax, by the way, so $host:$port
97     // should be written "tcp!$host!$port".  
98     "venti_server": "localhost",
99
100     // Where the vac and unvac binaries are kept:
101     "plan9bin": "/opt/plan9/bin",
102
103     // This is to make UGC work safely out of the box.  Hopefully no browser is
104     // dumb enough to run stuff inside <script> tags in something we're serving
105     // as text/plain:
106     "mime_substitutions": {
107       "text/html": "text/plain"
108     }
109   }
110
111 = Usage
112
113 Afer configuring, you can run the server with `webvac-server`.  This
114 will actually serve the content from venti, as long as it is present in
115 the path→score index in Redis (so you can remove content as needed by
116 just removing items from the index).  In order to add items, you run
117 `webvac-sweep`.  You can also delete the file (which will only happen if
118 the sweep is successful) with `-d`.
119
120 = TODO
121
122 See doc/TODO
123
124 = See also:
125
126 "Venti: a new approach to archival storage": http://doc.cat-v.org/plan_9/4th_edition/papers/venti/
127
128 "Pleroma":  https://pleroma.social/
129
130 = I feel dirty
131
132 You can throw Bitcoin (BTC) at this address:  1BZz3ndJUoWhEvm1BfW3FzceAjFqKTwqWV .  Proceeds will go to funding the instance hosting thing.