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