Initial community documentation
Community documentation is being written in Markdown format because we can leverage GitHub.com's ability to render Markdown into HTML directly from files in the repo. Also, the GlusterFS Community project has decided to use Markdown as an input into the tool called pandoc which can convert the documents into multiple formats. Change-Id: Iec530f05a9a1ab3a95a1e97b791e8390068b99b4 Signed-off-by: Luis Pabon <lpabon@redhat.com> Reviewed-on: http://review.gluster.org/5256 Reviewed-by: Peter Portante <pportant@redhat.com> Tested-by: Peter Portante <pportant@redhat.com>
This commit is contained in:
Luis Pabon
Peter Portante
parent
cc97abca04
commit
92fdc68d6b
28
README
28
README
@ -1,28 +0,0 @@
|
||||
Gluster For Swift - Integrating GlusterFS with OpenStack Swift Implementation
|
||||
of the Swift API. This is a component of the Unified File and Object (UFO)
|
||||
story for GlusterFS, which allows files and directories created via
|
||||
gluster-native/nfs/samba mount(s) to be accessed as accounts, containers and
|
||||
objects.
|
||||
|
||||
Install
|
||||
* yum install openstack-swift*.noarch
|
||||
* yum install gluster-swift-1.3*.noarch
|
||||
|
||||
Once this is done, you can access GlusterFS volumes via the Swift API where
|
||||
accounts are mounted volumes (today), containers are top-level directories,
|
||||
and objects are files and sub-directories of container directories.
|
||||
|
||||
Command to start the servers (TBD)
|
||||
swift-init main start
|
||||
|
||||
Command to stop the servers (TBD)
|
||||
swift-init main stop
|
||||
|
||||
Command to gracefully reload the servers
|
||||
swift-init main reload
|
||||
|
||||
Building RPMs. RPMs will be located in the 'build' directory.
|
||||
$ bash makerpm.sh
|
||||
|
||||
Building RPM with a specific release value, useful for automatic Jenkin builds
|
||||
$ PROG_RELEASE=123 bash makerpm.sh
|
||||
12
README.md
Normal file
12
README.md
Normal file
@ -0,0 +1,12 @@
|
||||
# Gluster For Swift
|
||||
Integrating GlusterFS as the back-end to OpenStack Swift
|
||||
implementation. This is a component of the Unified File and Object (UFO)
|
||||
story for GlusterFS, which allows files and directories created via
|
||||
gluster-native/nfs/samba mount(s) to be accessed as objects via
|
||||
the Swift API.
|
||||
|
||||
# Table of Contents
|
||||
1. [Overview and Concepts](doc/markdown/concepts.md)
|
||||
1. [Usage Guide](doc/markdown/user_guide.md)
|
||||
1. [Developer Guide](doc/markdown/dev_guide.md)
|
||||
|
||||
2
doc/markdown/concepts.md
Normal file
2
doc/markdown/concepts.md
Normal file
@ -0,0 +1,2 @@
|
||||
# Overview and Concepts
|
||||
TBD
|
||||
186
doc/markdown/dev_guide.md
Normal file
186
doc/markdown/dev_guide.md
Normal file
@ -0,0 +1,186 @@
|
||||
# Developer Guide
|
||||
|
||||
## Contributing to the project
|
||||
|
||||
## Development Environment Setup
|
||||
The workflow for Gluster-Swift is largely based upon the
|
||||
[OpenStack Gerrit Workflow][].
|
||||
|
||||
### Account Setup
|
||||
Gluster for Swift uses [Gerrit][] as a code review system. Create an
|
||||
account in [review.gluster.org][], then generate and upload
|
||||
an [SSH key][] to the website. This will allow you to upload
|
||||
changes to Gerrit. Follow the the information given
|
||||
at [GitHub Generating SSH Keys][] if you need help creating your key.
|
||||
|
||||
### Download the source
|
||||
The source for Gluster for Swift is available in Github. To download
|
||||
type:
|
||||
|
||||
~~~
|
||||
git clone https://github.com/gluster/gluster-swift.git
|
||||
cd gluster-swift
|
||||
~~~
|
||||
|
||||
### Git Review
|
||||
The tool `git review` is a simple tool to automate interaction with Gerrit.
|
||||
We recommend using this tool to upload, modify, and query changes in Gerrit.
|
||||
The tool can be installed by running the following command:
|
||||
|
||||
~~~
|
||||
pip install git-review
|
||||
~~~
|
||||
|
||||
Note that while many distros offer a version of `git review`, they don't
|
||||
necessarily keep it up to date. Pip gives one the latest which
|
||||
often avoids problems with various Gerrit servers.
|
||||
|
||||
We now need to setup `git review` to communicate with review.gluster.org.
|
||||
First, let's determine our `git review` setup by typing:
|
||||
|
||||
~~~
|
||||
git review -s
|
||||
~~~
|
||||
|
||||
If there is no output, then everything is setup correctly. If the output
|
||||
contains the string *We don't know where your gerrit is*, then we need
|
||||
a setup a remote repo with the name `gerrit`. We can inspect the current
|
||||
remote repo's by typing the following command.
|
||||
|
||||
~~~
|
||||
git remote -v
|
||||
~~~
|
||||
|
||||
To add the Gerrit remote repo, type the following:
|
||||
|
||||
~~~
|
||||
git remote add gerrit ssh://<username>@review.gluster.org/gluster-swift
|
||||
git remote -v
|
||||
~~~
|
||||
|
||||
Now we can confirm that `git review` has been setup by typing the
|
||||
following and noticing no output is returned:
|
||||
|
||||
~~~
|
||||
git review -s
|
||||
~~~
|
||||
|
||||
### Tox and Nose
|
||||
Like OpenStack Swift, Gluster for Swift uses `tox` python virtual
|
||||
environment for its unit tests. To install `tox` type:
|
||||
|
||||
~~~
|
||||
pip install tox nose
|
||||
~~~
|
||||
|
||||
## Workflow
|
||||
|
||||
### Create a topic branch
|
||||
It is recommended to create a branch in git when working on a specific topic.
|
||||
If you are currently on the *master* branch, you can type the following
|
||||
to create a topic branch:
|
||||
|
||||
~~~
|
||||
git checkout -b TOPIC-BRANCH
|
||||
~~~
|
||||
|
||||
where *TOPIC-BRANCH* is either bug/bug-number (e.g. bug/123456) or
|
||||
a meaningful name for the topic (e.g. feature_xyz)
|
||||
|
||||
### Quality Checking
|
||||
#### PEP8
|
||||
To test that the code adheres to the [PEP8][] specification, please
|
||||
type:
|
||||
|
||||
~~~
|
||||
tox -e pep8
|
||||
~~~
|
||||
|
||||
#### Unit Tests
|
||||
You can run the unit tests after making your changes. To run the unit
|
||||
test suite in `tox` type the following as a non-root user:
|
||||
|
||||
~~~
|
||||
tox -e ENV
|
||||
~~~
|
||||
|
||||
where *ENV* is either `py27` for systems with Python 2.7+, or `py26` for
|
||||
systems with Python 2.6+.
|
||||
|
||||
#### Functional Tests
|
||||
Fuctional tests are used to test a running Gluster for Swift environment.
|
||||
**TBD**.
|
||||
|
||||
### Commiting changes
|
||||
After making the changes needed, you can commit your changes by typing:
|
||||
|
||||
~~~
|
||||
git commit -as
|
||||
~~~
|
||||
|
||||
where the commit message should follow the following recommendations:
|
||||
|
||||
1. The first line should be a brief message and contain less than 50
|
||||
characters.
|
||||
2. Second line blank
|
||||
3. A line, or multiple line description of the change where each line
|
||||
contains less than 70 characters.
|
||||
4. Blank line
|
||||
5. If this is a bug fix, then it should have a line as follows:
|
||||
`BUG 12345: <url to bug>`
|
||||
6. Blank line.
|
||||
|
||||
For more information on commit messages, please visit the
|
||||
[Git Commit Messages][] page in OpenStack.org.
|
||||
|
||||
### Uploading to Gerrit
|
||||
Once you have the changes ready for review, you can submit it to Gerrit
|
||||
simply by typing:
|
||||
|
||||
~~~
|
||||
git review
|
||||
~~~
|
||||
|
||||
After the change is reviewed, most likely you may have to make some
|
||||
additional modifications to your change. To continue the work for
|
||||
a specific change, you can query Gerrit for the change number by
|
||||
typing:
|
||||
|
||||
~~~
|
||||
git review -l
|
||||
~~~
|
||||
|
||||
Then download the change to make the new modifications by typing:
|
||||
|
||||
~~~
|
||||
git review -d CHANGE_NUMBER
|
||||
~~~
|
||||
|
||||
where CHANGE_NUMBER is the Gerrit change number.
|
||||
|
||||
## Creating Distribution Packages
|
||||
|
||||
### Tools Installation
|
||||
TBD: For now please follow the installation instructions
|
||||
on the [GlusterFS Compiling RPMS][] page.
|
||||
|
||||
### Building RPMs for Fedora/RHEL/CentOS Systems
|
||||
Building RPMs. RPMs will be located in the *build* directory.
|
||||
|
||||
`$ bash makerpm.sh`
|
||||
|
||||
Building RPM with a specific release value, useful for automatic
|
||||
Jenkin builds, or keeping track of different versions of the
|
||||
RPM:
|
||||
|
||||
`$ PKG_RELEASE=123 bash makerpm.sh`
|
||||
|
||||
|
||||
[OpenStack Gerrit Workflow]: https://wiki.openstack.org/wiki/Gerrit_Workflow
|
||||
[Gerrit]: https://code.google.com/p/gerrit/
|
||||
[review.gluster.org]: http://review.gluster.org
|
||||
[SSH Key]: http://review.gluster.org/#/settings/ssh-keys
|
||||
[GitHub Generating SSH Keys]: https://help.github.com/articles/generating-ssh-keys
|
||||
[PEP8]: http://www.python.org/dev/peps/pep-0008
|
||||
[Git Commit Messages]: https://wiki.openstack.org/wiki/GitCommitMessages
|
||||
[GlusterFS Compiling RPMS]: https://forge.gluster.org/glusterfs-core/pages/CompilingRPMS
|
||||
66
doc/markdown/user_guide.md
Normal file
66
doc/markdown/user_guide.md
Normal file
@ -0,0 +1,66 @@
|
||||
# User Guide
|
||||
|
||||
## Installation
|
||||
|
||||
### GlusterFS Installation
|
||||
First, we need to install GlusterFS on the system by following the
|
||||
instructions on [GlusterFS QuickStart Guide][].
|
||||
|
||||
### Fedora/RHEL/CentOS
|
||||
Gluster for Swift depends on OpenStack Swift Grizzly, which can be
|
||||
obtained by using [RedHat's RDO][] packages as follows:
|
||||
|
||||
~~~
|
||||
yum install -y http://rdo.fedorapeople.org/openstack/openstack-grizzly/rdo-release-grizzly.rpm
|
||||
~~~
|
||||
|
||||
### Download
|
||||
Gluster for Swift uses [Jenkins][] for continuous integration and
|
||||
creation of distribution builds. Download the latest RPM builds
|
||||
from one of the links below:
|
||||
|
||||
* RHEL/CentOS 6: [Download](http://build.gluster.org/job/gluster-swift-builds-cent6/lastSuccessfulBuild/artifact/build/)
|
||||
* Fedora 18+: [Download](http://build.gluster.org/job/gluster-swift-builds-f18/lastSuccessfulBuild/artifact/build/)
|
||||
|
||||
Install the downloaded RPM using the following command:
|
||||
|
||||
~~~
|
||||
yum install -y RPMFILE
|
||||
~~~
|
||||
|
||||
where *RPMFILE* is the RPM file downloaded from Jenkins.
|
||||
|
||||
## Configuration
|
||||
TBD
|
||||
|
||||
## Server Control
|
||||
Command to start the servers (TBD)
|
||||
|
||||
~~~
|
||||
swift-init main start
|
||||
~~~
|
||||
|
||||
Command to stop the servers (TBD)
|
||||
|
||||
~~~
|
||||
swift-init main stop
|
||||
~~~
|
||||
|
||||
Command to gracefully reload the servers
|
||||
|
||||
~~~
|
||||
swift-init main reload
|
||||
~~~
|
||||
|
||||
### Mounting your volumes
|
||||
TBD
|
||||
|
||||
Once this is done, you can access GlusterFS volumes via the Swift API where
|
||||
accounts are mounted volumes, containers are top-level directories,
|
||||
and objects are files and sub-directories of container directories.
|
||||
|
||||
|
||||
|
||||
[GlusterFS QuickStart Guide]: http://www.gluster.org/community/documentation/index.php/QuickStart
|
||||
[RedHat's RDO]: http://openstack.redhat.com/Quickstart
|
||||
[Jenkins]: http://jenkins-ci.org
|
||||
Loading…
Reference in New Issue
Block a user