Skip to content

Latest commit

 

History

History
96 lines (69 loc) · 4.09 KB

HACKING.md

File metadata and controls

96 lines (69 loc) · 4.09 KB
Raw

MicroCeph Hacking Guide

Wait! No-one's "hacking" anything. The aim of this document is to enable new developers/users get familiarised with the build tools and MicroCeph codebase so that they can build and contribute to the MicroCeph Codebase.

Table of Contents

  1. ⚡️ Introduction to snaps
  2. 🧰 Tools
  3. 📖 References
  4. 🏭 Build Guide
  5. 👍 Unit-Testing

⚡️ Introduction to snaps

A snap is a bundle of an app and its dependencies that works without modification across Linux distributions.

Apart from being a self-contained artifact, being a snap enables MicroCeph to be isolated from host and provide a clean and consistent building, installing and cleanup experience.

The microceph snap packages all the required ceph-binaries, dqlite and a small management daemon (microcephd) which ties all of this together. Using the light-weight distributed dqlite layer, MicroCeph enables orchestration of a ceph cluster in a centralised and easy to use manner.

🧰 Tools

Snaps are built and published using another snap called snapcraft. It uses lxd to pull dependencies and build an artifact completely isolated from the host system. This makes it easier for developers to work on MicroCeph without polluting their host system with unwanted dependencies. You can install snapcraft and lxd using snap tool.

sudo snap install snapcraft --classic
sudo snap install lxd

NOTE: For a detailed how-to-use snapcraft tool guide, check-out Snap-Tutorials

📖 References

The MicroCeph codebase resides inside the microceph sub-directory of the repo. This subdir is neatly organised into parts which make up the whole of MicroCeph. Below is a brief description of what can be found in each of those parts for reference.

Sub Directories

  1. api

    Contains files related to the internal REST APIs which the microceph client uses to communicate to the microceph daemon. It also contains a types subdir which has necessary data structures for the APIs.

  2. ceph

    Contains files directly related to ceph orchestration. This includes code for ceph cluster configuration, service orchestration etc.

  3. client

    Contains REST client code which is used by microceph CLI for interacting with microceph daemon.

  4. cmd

    Contains microceph CLI commands written with Cobra Commands

  5. common

    Contains common code

  6. database

    Contains DQlite schema and migration definitions along with generated mappers for DB interfacing.

  7. mocks

    Contains mock definitions for unit testing

🏭 Build Guide

Building MicroCeph is as easy as a snap!

# v for verbose output of the build process.
snapcraft -v
...
Creating snap package 
...                                                                                                                                                                     
Created snap package microceph_0+git.ac1da26_amd64.snap

The newly created .snap artifact can then be installed as

# Dangerous flag for locally built snap
sudo snap install --dangerous microceph_*.snap 
# Locally built snaps do no auto-connect the available plugs on install, they can be connected manually using;
sudo snap connect microceph:block-devices
sudo snap connect microceph:hardware-observe
sudo snap connect microceph:dm-crypt
sudo snap restart microceph.daemon

👍 Unit-Testing

The MicroCeph makefile has targets for running unit tests and lint checks. They can be run as follows.

# Note: commands executed from microceph subdir which contains the Makefile.
# Run unit tests
make check-unit

# Run static checks
make check-static