README

   1 = omgdav - Rack app for exposing MogileFS via WebDAV
   2
   3 omgdav exposes an existing MogileFS domain over WebDAV.  There is
   4 absolutely no commitment or modification needed to your existing
   5 MogileFS installation to try omgdav in read-only mode.
   6
   7 omgdav uses its own database and can import key listings from with an
   8 existing MogileFS domain.
   9
  10 omgdav (barely :P) meets class 1 WebDAV compliance according to
  11 litmus[1].  Class 2 compliance is planned.
  12
  13 *** WARNING ***
  14 ---------------
  15
  16 Locking of any type is not yet implemented.  Thus:
  17
  18 1) Do not attempt concurrent invocations of COPY/MOVE commands.
  19
  20 2) Do not use PUT or DELETE while a COPY or MOVE command is running.
  21
  22 If you are using fusedav, rmdir will remove directories due to
  23 the way DELETE works on both collections and files.
  24
  25 Read-only operation is currently the safest way to use omgdav.
  26
  27 Features
  28 --------
  29
  30 * Allows read-only access to existing MogileFS data with a WebDAV client.
  31
  32 * Infers WebDAV collections based on existing MogileFS keys which
  33   look like path names (e.g. "/parts/separated/by/slashes").
  34
  35 * Implemented for Rack, so it is compatible with existing middlewares
  36   (for authentication, logging, etc...) and Rack web servers.
  37
  38 Requirements
  39 ------------
  40
  41 * an existing MogileFS instance
  42
  43 * Ruby 1.9.3 or later (any Ruby implementation compatible with C extensions)
  44
  45 * a Free, Unix-like operating system (GNU/Linux preferred)
  46
  47 * a Free database supported by Sequel[2]
  48
  49 Install (via RubyGems)
  50 ----------------------
  51
  52         gem install omgdav
  53
  54 Usage
  55 -----
  56
  57 1. Setup your database:
  58
  59         # You may substitute the sqlite:/// database for any other
  60         # Free database type Sequel supports.  Be sure to have the
  61         # appropriate database driver installed (e.g. "sqlite3").
  62         omgdav-setup sqlite://test.sqlite
  63
  64 omgdav-setup runs idempotently.  It will automatically upgrade your
  65 schema as new versions of omgdav may require database updates
  66
  67 2. Sync metadata from your existing MogileFS domain:
  68
  69         omgdav-sync -t $TRACKER_HOST_PORT -d $DOMAIN sqlite://test.sqlite
  70
  71 omgdav-sync runs idempotently.  It may be used to resync changes
  72 to the omgdav database if keys are added/removed from MogileFS.
  73
  74 3. Configure your rackup config file, below is an example config.ru:
  75
  76 ------------------------------------- 8<------------------------------------
  77 require "omgdav/app"
  78 # replace hosts: and domain: with values suitable for your cluster
  79 mogc = MogileFS::MogileFS.new(hosts: %w(127.0.0.1:7001), domain: "test")
  80 db = Sequel.connect("sqlite://test.sqlite")
  81
  82 # for the brave: :ro ("read-only") may be swapped for :rw ("read-write")
  83 # :worm is also supported ("write-once, read-many")
  84 run OMGDAV::App.new(db, mogc, methods: :ro)
  85 ------------------------------------- 8<------------------------------------
  86
  87 4. Start your Rack HTTP server and point your WebDAV client at it.
  88
  89         rackup -s webrick -p $PORT config.ru
  90
  91 Code
  92 ----
  93
  94 Source code is available via git:
  95
  96         git clone https://bogomips.org/omgdav.git
  97         git clone https://repo.or.cz/omgdav.git
  98
  99 And viewable with a WWW browser:
 100
 101         https://bogomips.org/omgdav.git
 102         https://repo.or.cz/w/omgdav.git (gitweb)
 103
 104 Contact
 105 -------
 106
 107 Bug reports, user/development discussion, patches, pull requests are
 108 greatly appreciated via plain-text email.
 109
 110 We may also piggy-back onto the public MogileFS
 111 mailing list at mailto:mogile@googlegroups.com for feedback.
 112
 113 HTML email will be mercilessly rejected.
 114
 115 License
 116 -------
 117 omgdav is copyrighted Free Software by all contributors, see logs in
 118 revision control for names and email addresses of all of them.
 119
 120 You can redistribute omgdav and/or modify it under the terms of the GNU
 121 Affero General Public License, version 3 or later as published by the
 122 Free Software Foundation.
 123
 124 omgdav is distributed in the hope that it will be useful, but WITHOUT
 125 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 126 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public
 127 License for more details.
 128
 129 You should have received a copy of the GNU Affero General Public License
 130 along with omgdav; if not, see https://www.gnu.org/licenses/agpl.txt
 131
 132 fusedav
 133 -------
 134
 135 Some testing and use of omgdav is done on fusedav[3].  Since fusedav
 136 upstream appears dormant, we have publicized some bug reports and
 137 patches on the Debian bug tracker[4].  Our fusedav patches are
 138 also available via various branches in our git repository:
 139
 140         git clone https://bogomips.org/fusedav.git
 141
 142 Links
 143 -----
 144 MogileFS - http://mogilefs.org/
 145 omgdav homepage - https://bogomips.org/omgdav/README
 146 omgdav Atom feed - https://bogomips.org/omgdav/NEWS.atom.xml
 147
 148 References
 149 ----------
 150 [1] litmus - http://www.webdav.org/neon/litmus/
 151 [2] Sequel - http://sequel.jeremyevans.net/
 152 [3] fusedav - http://0pointer.de/lennart/projects/fusedav/
 153 [4] fusedav (Debian BTS) - https://bugs.debian.org/fusedav