README.swift.rst

   1 Openstack Swift as backend for Dulwich
   2 ======================================
   3 Fabien Boucher <fabien.boucher@enovance.com>
   4
   5 The module dulwich/contrib/swift.py implements dulwich.repo.BaseRepo
   6 in order to being compatible with Openstack Swift.
   7 We can then use Dulwich as server (Git server) and instead of using
   8 a regular POSIX file system to store repository objects we use the
   9 object storage Swift via its own API.
  10
  11 c Git client <---> Dulwich server <---> Openstack Swift API
  12
  13 This implementation is still a work in progress and we can say that
  14 is a Beta version so you need to be prepared to find bugs.
  15
  16 Configuration file
  17 ------------------
  18
  19 We need to provide some configuration values in order to let Dulwich
  20 talk and authenticate against Swift. The following config file must
  21 be used as template::
  22
  23     [swift]
  24     # Authentication URL (Keystone or Swift)
  25     auth_url = http://127.0.0.1:5000/v2.0
  26     # Authentication version to use
  27     auth_ver = 2
  28     # The tenant and username separated by a semicolon
  29     username = admin;admin
  30     # The user password
  31     password = pass
  32     # The Object storage region to use (auth v2) (Default RegionOne)
  33     region_name = RegionOne
  34     # The Object storage endpoint URL to use (auth v2) (Default internalURL)
  35     endpoint_type = internalURL
  36     # Concurrency to use for parallel tasks (Default 10)
  37     concurrency = 10
  38     # Size of the HTTP pool (Default 10)
  39     http_pool_length = 10
  40     # Timeout delay for HTTP connections (Default 20)
  41     http_timeout = 20
  42     # Chunk size to read from pack (Bytes) (Default 12228)
  43     chunk_length = 12228
  44     # Cache size (MBytes) (Default 20)
  45     cache_length = 20
  46
  47
  48 Note that for now we use the same tenant to perform the requests
  49 against Swift. Therefor there is only one Swift account used
  50 for storing repositories. Each repository will be contained in
  51 a Swift container.
  52
  53 How to start unittest
  54 ---------------------
  55
  56 There is no need to have a Swift cluster running to run the unitests.
  57 Just run the following command in the Dulwich source directory::
  58
  59     $ PYTHONPATH=. python -m dulwich.contrib.test_swift
  60
  61 How to start functional tests
  62 -----------------------------
  63
  64 We provide some basic tests to perform smoke tests against a real Swift
  65 cluster. To run those functional tests you need a properly configured
  66 configuration file. The tests can be run as follow::
  67
  68     $ DULWICH_SWIFT_CFG=/etc/swift-dul.conf PYTHONPATH=. python -m dulwich.contrib.test_swift_smoke
  69
  70 How to install
  71 --------------
  72
  73 Install the Dulwich library via the setup.py. The dependencies will be
  74 automatically retrieved from pypi::
  75
  76     $ python ./setup.py install
  77
  78 How to run the server
  79 ---------------------
  80
  81 Start the server using the following command::
  82
  83     $ python -m dulwich.contrib.swift daemon -c /etc/swift-dul.conf -l 127.0.0.1
  84
  85 Note that a lot of request will be performed against the Swift
  86 cluster so it is better to start the Dulwich server as close
  87 as possible of the Swift proxy. The best solution is to run
  88 the server on the Swift proxy node to reduce the latency.
  89
  90 How to use
  91 ----------
  92
  93 Once you have validated that the functional tests is working as expected and
  94 the server is running we can init a bare repository. Run this
  95 command with the name of the repository to create::
  96
  97     $ python -m dulwich.contrib.swift init -c /etc/swift-dul.conf edeploy
  98
  99 The repository name will be the container that will contain all the Git
 100 objects for the repository. Then standard c Git client can be used to
 101 perform operations against this repository.
 102
 103 As an example we can clone the previously empty bare repository::
 104
 105     $ git clone git://localhost/edeploy
 106
 107 Then push an existing project in it::
 108
 109     $ git clone https://github.com/enovance/edeploy.git edeployclone
 110     $ cd edeployclone
 111     $ git remote add alt git://localhost/edeploy
 112     $ git push alt master
 113     $ git ls-remote alt
 114     9dc50a9a9bff1e232a74e365707f22a62492183e        HEAD
 115     9dc50a9a9bff1e232a74e365707f22a62492183e        refs/heads/master
 116
 117 The other Git commands can be used the way you do usually against
 118 a regular repository.
 119
 120 Note the daemon subcommands starts a Git server listening for the
 121 Git protocol. Therefor there is no authentication or encryption
 122 at all between the cGIT client and the GIT server (Dulwich).
 123
 124 Note on the .info file for pack object
 125 --------------------------------------
 126
 127 The Swift interface of Dulwich relies only on the pack format
 128 to store Git objects. Instead of using only an index (pack-sha.idx)
 129 along with the pack, we add a second file (pack-sha.info). This file
 130 is automatically created when a client pushes some references on the
 131 repository. The purpose of this file is to speed up pack creation
 132 server side when a client fetches some references. Currently this
 133 .info format is not optimized and may change in future.