README

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