ceph/doc/dev/quick_guide.rst

   1 =================================
   2  Developer Guide (Quick)
   3 =================================
   4
   5 This guide will describe how to build and test Ceph for development.
   6
   7 Development
   8 -----------
   9
  10 The ``run-make-check.sh`` script will install Ceph dependencies,
  11 compile everything in debug mode and run a number of tests to verify
  12 the result behaves as expected.
  13
  14 .. code::
  15
  16        $ ./run-make-check.sh
  17
  18
  19 Running a development deployment
  20 --------------------------------
  21 Ceph contains a script called ``vstart.sh`` (see also :doc:`/dev/dev_cluster_deployement`) which allows developers to quickly test their code using
  22 a simple deployment on your development system. Once the build finishes successfully, start the ceph
  23 deployment using the following command:
  24
  25 .. code::
  26
  27         $ cd ceph/build  # Assuming this is where you ran cmake
  28         $ make vstart
  29         $ ../src/vstart.sh -d -n -x
  30
  31 You can also configure ``vstart.sh`` to use only one monitor and one metadata server by using the following:
  32
  33 .. code::
  34
  35         $ MON=1 MDS=1 ../src/vstart.sh -d -n -x
  36
  37 The system creates three pools on startup: `cephfs_data`, `cephfs_metadata`, and `rbd`.  Let's get some stats on
  38 the current pools:
  39
  40 .. code::
  41
  42         $ bin/ceph osd pool stats
  43         *** DEVELOPER MODE: setting PATH, PYTHONPATH and LD_LIBRARY_PATH ***
  44         pool rbd id 0
  45           nothing is going on
  46
  47         pool cephfs_data id 1
  48           nothing is going on
  49
  50         pool cephfs_metadata id 2
  51           nothing is going on
  52
  53         $ bin/ceph osd pool stats cephfs_data
  54         *** DEVELOPER MODE: setting PATH, PYTHONPATH and LD_LIBRARY_PATH ***
  55         pool cephfs_data id 1
  56           nothing is going on
  57
  58         $ ./rados df
  59         pool name       category                 KB      objects       clones     degraded      unfound     rd        rd KB           wr        wr KB
  60         rbd             -                          0            0            0            0     0            0            0            0            0
  61         cephfs_data     -                          0            0            0            0     0            0            0            0            0
  62         cephfs_metadata -                          2           20            0           40     0            0            0           21            8
  63           total used        12771536           20
  64           total avail     3697045460
  65           total space     3709816996
  66
  67
  68 Make a pool and run some benchmarks against it:
  69
  70 .. code::
  71
  72         $ bin/rados mkpool mypool
  73         $ bin/rados -p mypool bench 10 write -b 123
  74
  75 Place a file into the new pool:
  76
  77 .. code::
  78
  79         $ bin/rados -p mypool put objectone <somefile>
  80         $ bin/rados -p mypool put objecttwo <anotherfile>
  81
  82 List the objects in the pool:
  83
  84 .. code::
  85
  86         $ bin/rados -p mypool ls
  87
  88 Once you are done, type the following to stop the development ceph deployment:
  89
  90 .. code::
  91
  92         $ ../src/stop.sh
  93
  94 Resetting your vstart environment
  95 ---------------------------------
  96
  97 The vstart script creates out/ and dev/ directories which contain
  98 the cluster's state.  If you want to quickly reset your environment,
  99 you might do something like this:
 100
 101 .. code::
 102
 103     [build]$ ../src/stop.sh
 104     [build]$ rm -rf out dev
 105     [build]$ MDS=1 MON=1 OSD=3 ../src/vstart.sh -n -d
 106
 107 Running a RadosGW development environment
 108 -----------------------------------------
 109
 110 Set the ``RGW`` environment variable when running vstart.sh to enable the RadosGW.
 111
 112 .. code::
 113
 114         $ cd build
 115         $ RGW=1 ../src/vstart.sh -d -n -x
 116
 117 You can now use the swift python client to communicate with the RadosGW.
 118
 119 .. code::
 120
 121     $ swift -A http://localhost:8000/auth -U test:tester -K testing list
 122     $ swift -A http://localhost:8000/auth -U test:tester -K testing upload mycontainer ceph
 123     $ swift -A http://localhost:8000/auth -U test:tester -K testing list
 124
 125
 126 Run unit tests
 127 --------------
 128
 129 The tests are located in `src/tests`.  To run them type:
 130
 131 .. code::
 132
 133         $ make check
 134