x
/
compass-core
Code Issues Proposed changes

update README.md to describe the code base in high level 

Change-Id: Ic932572382d7e906a722ebcb4845740daf8cfe01
This commit is contained in:
Shuo Yang 2015-06-12 11:57:07 -07:00
parent b472f821c4
commit fb0dafb505
1 changed files with 81 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

123
README.md
View File

@ -1,19 +1,58 @@
Compass
=======
A Deoployment Automation System. See Wiki page at https://wiki.openstack.org/wiki/Compass.
## Overview
Porject homepage: http://www.syscompass.org/
How to use in production environments: http://www.syscompass.org/install.html
As a platform-independent deployment automation system, Compass simplifies the complex and error-prone deployment process of various distributed systems such as Openstack, Ceph and so on. It dramatically reduces the time of datacenter server management. Compass, designed with an extensible architecture, can be easily integrated with most of the popular automation
tools (Cobbler, Chef, Ansible) and allows third-parties (vendors) plugins for hardware discovery.
Try compass out: http://www.syscompass.org/user.html
#### [Visit Our Official Project Webiste](http://www.syscompass.org/)
Quick Guide
-----------
#### [Visit Our Wiki Page for OpenStack Users](https://wiki.openstack.org/wiki/Compass)
##Quick Guide to Developers
### Directories (How codebase is organized)
* bin/ - contains Compass utility scripts
* compass/ - contains all Compass business logic including database & backend
* api/ - contains Compass RESTful APIs implementation
* actions/ - interface to essential functionalities executed by Celery tasks, including deploy, find servers and so on
* apiclient/ - contains Compass RESTful API client
* db/ - contains database model and supported database operations
* deployment/ - contains the module for deploying a distributed system from OS installation to package installation based on user configuration via RESTful or Web UI.
* hdsdiscovery/ - contains the module for learning server hardware spec
* log_analyzor/ - library to calculate installation progress by processing logs from the servers being deployed
* tasks/ - definition of Celery tasks triggering Compass actions
* utils/ - contains utility functions for other modules
* tests/ - unittests level testing code
* tests_serverside/ - tests that Compass's functionality to communicate with a known chef server
* install/ - contains scripts for Compass installation on virtual machine or bare metal server
* service/ - contains Compass messaging service and cluster installation progress service
Quick Guide to Users
--------------------
### Install Compass from source?
How to install Compass?
-----------------------
1. Run `git clone -b dev/exeperimental git://git.openstack.org/stackforge/compass-core.git`
2. Run `cd compass` to the Compass project directory.
3. Run `./install/install.sh` to setup compass environment. Please note that before you execute `install.sh`, you may setup your environment variables in `install/install.conf`, explanations and examples of those variables can be found in `install.conf`.
@ -21,8 +60,8 @@ How to install Compass?
6. Run `service compass-celeryd start` to start compass celery daemon service.
7. Run `service compass-progress-updated start` to start compass progress update daemon service.
How to play Compass?
--------------------
### How to play Compass?
1. Make sure your host is one of: mac/ubuntu trusty/ubuntu precise.
2. Make sure your OS and CPU architecture are both 64-bit.
3. Make sure you have virtualbox installed.
@ -32,46 +71,46 @@ How to play Compass?
7. Run `./launch.sh`
Note: all the vboxnet interfaces and compass related vms should be removed prior to another launch.
FAQ
---
* Why doesn't celery start? What should I do if I get `celery died but pid file exists` message after running `service compassd status`?
### FAQ
1. Simply remove celery pid file (`/var/run/celery.pid`).
2. Try running `export C_FORCE_ROOT=1`
3. Restart Compass celery daemon.
* Why doesn't celery start? What should I do if I get `celery died but pid file exists` message after running `service compassd status`?
* How to check if the compass services run properly?
1. Run `service compass-celeryd status` and `compass-progress-updated status` to check compass services status.
2. Run `service httpd status` to check web service status.
1. Simply remove celery pid file (`/var/run/celery.pid`).
2. Try running `export C_FORCE_ROOT=1`
3. Restart Compass celery daemon.
* How to troubleshoot if `compassd` can not start the services?
1. Try to remove /var/run/celeryd.pid to release the celeryd lock
2. Try to remove /var/run/progress_update.pid to release the progress_update lock.
* How to check if the compass services run properly?
1. Run `service compass-celeryd status` and `compass-progress-updated status` to check compass services status.
2. Run `service httpd status` to check web service status.
* How to use compass to install distributed systems?
* How to troubleshoot if `compassd` can not start the services?
1. Try to remove /var/run/celeryd.pid to release the celeryd lock
2. Try to remove /var/run/progress_update.pid to release the progress_update lock.
Access http://<server_ip>. `http://www.syscompass.org/install.html` has some UI instructions.
* How to use compass to install distributed systems?
* How to run unittest?
1. `. ~/.virtualenvs/compass-core/bin/activate` to activate compass python venv
2. go to compass-core directory
3. make sure you have dependency packages installed, if you used compass install scripts to install compass, they are already installed
4. run `tox -epy26` or `tox -pey27` depending on your python version.
Access http://<server_ip>. `http://www.syscompass.org/install.html` has some UI instructions.
* Where to find the log file?
1. `/var/log/compass/compass.log` is the compass web log.
2. `/var/log/compass/celery.log` is the celery log, celery logs contain most important debugging information.
3. The redirected celeryd stdout/stderr is at `/tmp/celeryd.log`.
4. The redirected progress_update.py stdout/stderr is at `/tmp/progress_update.log`
5. The web server (httpd) log files are under `/var/log/httpd/`.
* How to run unittest?
1. `. ~/.virtualenvs/compass-core/bin/activate` to activate compass python venv
2. go to compass-core directory
3. make sure you have dependency packages installed, if you used compass install scripts to install compass, they are already installed
4. run `tox -epy26` or `tox -pey27` depending on your python version.
* Where to find the compass config file?
1. the compass setting file is at /etc/compass/setting.
2. the default global config file for installing distributed system is at /etc/compass/setting
3. the default celery config file is at /etc/compass/celeryconfig
4. adapters, templates and flavor configs are at /etc/compass/ as well.
* Where to find the log file?
1. `/var/log/compass/compass.log` is the compass web log.
2. `/var/log/compass/celery.log` is the celery log, celery logs contain most important debugging information.
3. The redirected celeryd stdout/stderr is at `/tmp/celeryd.log`.
4. The redirected progress_update.py stdout/stderr is at `/tmp/progress_update.log`
5. The web server (httpd) log files are under `/var/log/httpd/`.
* Where to find the compass config file?
1. the compass setting file is at /etc/compass/setting.
2. the default global config file for installing distributed system is at /etc/compass/setting
3. the default celery config file is at /etc/compass/celeryconfig
4. adapters, templates and flavor configs are at /etc/compass/ as well.
* Where are the utility scripts for compass?
They are at `/opt/compass/bin/`
* Where are the utility scripts for compass?
They are at `/opt/compass/bin/`