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 two pools on startup: `cephfs_data_a` and `cephfs_metadata_a`.  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 cephfs_data_a id 1
  45           nothing is going on
  46
  47         pool cephfs_metadata_a id 2
  48           nothing is going on
  49
  50         $ bin/ceph osd pool stats cephfs_data_a
  51         *** DEVELOPER MODE: setting PATH, PYTHONPATH and LD_LIBRARY_PATH ***
  52         pool cephfs_data_a id 1
  53           nothing is going on
  54
  55         $ bin/rados df
  56         POOL_NAME         USED OBJECTS CLONES COPIES MISSING_ON_PRIMARY UNFOUND DEGRADED RD_OPS RD WR_OPS WR
  57         cephfs_data_a        0       0      0      0                  0       0        0      0  0      0    0
  58         cephfs_metadata_a 2246      21      0     63                  0       0        0      0  0     42 8192
  59
  60         total_objects    21
  61         total_used       244G
  62         total_space      1180G
  63
  64
  65 Make a pool and run some benchmarks against it:
  66
  67 .. code::
  68
  69         $ bin/rados mkpool mypool
  70         $ bin/rados -p mypool bench 10 write -b 123
  71
  72 Place a file into the new pool:
  73
  74 .. code::
  75
  76         $ bin/rados -p mypool put objectone <somefile>
  77         $ bin/rados -p mypool put objecttwo <anotherfile>
  78
  79 List the objects in the pool:
  80
  81 .. code::
  82
  83         $ bin/rados -p mypool ls
  84
  85 Once you are done, type the following to stop the development ceph deployment:
  86
  87 .. code::
  88
  89         $ ../src/stop.sh
  90
  91 Resetting your vstart environment
  92 ---------------------------------
  93
  94 The vstart script creates out/ and dev/ directories which contain
  95 the cluster's state.  If you want to quickly reset your environment,
  96 you might do something like this:
  97
  98 .. code::
  99
 100     [build]$ ../src/stop.sh
 101     [build]$ rm -rf out dev
 102     [build]$ MDS=1 MON=1 OSD=3 ../src/vstart.sh -n -d
 103
 104 Running a RadosGW development environment
 105 -----------------------------------------
 106
 107 Set the ``RGW`` environment variable when running vstart.sh to enable the RadosGW.
 108
 109 .. code::
 110
 111         $ cd build
 112         $ RGW=1 ../src/vstart.sh -d -n -x
 113
 114 You can now use the swift python client to communicate with the RadosGW.
 115
 116 .. code::
 117
 118     $ swift -A http://localhost:8000/auth -U test:tester -K testing list
 119     $ swift -A http://localhost:8000/auth -U test:tester -K testing upload mycontainer ceph
 120     $ swift -A http://localhost:8000/auth -U test:tester -K testing list
 121
 122
 123 Run unit tests
 124 --------------
 125
 126 The tests are located in `src/tests`.  To run them type:
 127
 128 .. code::
 129
 130         $ make check
 131