summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--doc/markdown/quick_start_guide.md301
1 files changed, 129 insertions, 172 deletions
diff --git a/doc/markdown/quick_start_guide.md b/doc/markdown/quick_start_guide.md
index 0b0990f..9312ae9 100644
--- a/doc/markdown/quick_start_guide.md
+++ b/doc/markdown/quick_start_guide.md
@@ -2,196 +2,158 @@
## Contents
* [Overview](#overview)
-* [System Setup](#system_setup)
-* [Gluster For Swift Setup](#swift_setup)
+* [Setting up GlusterFS](#gluster_setup)
+* [Setting up gluster-swift](#swift_setup)
* [Using Gluster for Swift](#using_swift)
-* [Accessing over Amazon S3 API](s3.md)
* [What now?](#what_now)
<a name="overview" />
## Overview
-Gluster-swift allows GlusterFS to be used as the backend to the object
-store OpenStack Swift.
+Gluster-swift project enables object based access (over Swift and S3 API)
+to GlusterFS volumes.This guide is a great way to begin using gluster-swift,
+and can be easily deployed on a single virtual machine. The final result
+will be a single gluster-swift node.
-The following guide will get you quickly started with a gluster-swift
-environment on a Fedora or RHEL/CentOS system. This guide is a
-great way to begin using gluster-swift, and can be easily deployed on
-a single virtual machine. The final result will be a single gluster-swift
-node.
+The instructions provided in this guide has been tested specifically on:
+* CentOS 7
+* Ubuntu 16.04.2 LTS 'xenial'
+
+If you are on other distributions, the steps related to where you fetch
+the installation packages may vary.
> NOTE: In Gluster-Swift, accounts must be GlusterFS volumes.
-<a name="system_setup" />
-## System Setup
+<a name="gluster_setup" />
+## Setting up GlusterFS
-### Prerequisites on CentOS/RHEL
-On CentOS/RHEL you will need to setup GlusterFS and EPEL repos.
+### Installing and starting GlusterFS
-#### GlusterFS CentOS/RHEL Repo
+If on Ubuntu 16.04:
-* CentOS
+```sh
+# add-apt-repository ppa:gluster/glusterfs-3.10
+# apt-get install glusterfs-server attr
+# service glusterfs-server start
+```
-~~~
-wget -O /etc/yum.repos.d/glusterfs-epel.repo \
- http://download.gluster.org/pub/gluster/glusterfs/LATEST/CentOS/glusterfs-epel.repo
-~~~
+If on CentOS 7:
-* RHEL
+```sh
+# yum install centos-release-gluster
+# yum install glusterfs-server
+# service glusterd start
+```
-~~~
-wget -O /etc/yum.repos.d/glusterfs-epel.repo \
- http://download.gluster.org/pub/gluster/glusterfs/LATEST/RHEL/glusterfs-epel.repo
-~~~
+### Setting up a GlusterFS volume
-#### EPEL CentOS/RHEL Repo
-Please refer to [EPEL][] for more information on how to setup the EPEL repo.
+You can use separate partitions as bricks. This guide illustrates using
+loopback devices as bricks.
-### Required Package Installation
-Install and start the required packages on your system to create a GlusterFS volume.
+Create bricks:
-~~~
-yum install glusterfs glusterfs-server glusterfs-fuse memcached xfsprogs
-~~~
+```sh
+# truncate -s 1GB /srv/disk{1..4}
+# for i in `seq 1 4`;do mkfs.xfs -i size=512 /srv/disk$i ;done
+# mkdir -p /export/brick{1..4}
+```
-#### Start services
-
-Type the following to start `memcached` and `glusterfs` services:
+Add the following lines to `/etc/fstab` to auto-mount the the bricks on system startup:
~~~
-service memcached start
-service glusterd start
+/srv/disk1 /export/brick1 xfs loop,inode64,noatime,nodiratime 0 0
+/srv/disk2 /export/brick2 xfs loop,inode64,noatime,nodiratime 0 0
+/srv/disk3 /export/brick3 xfs loop,inode64,noatime,nodiratime 0 0
+/srv/disk4 /export/brick4 xfs loop,inode64,noatime,nodiratime 0 0
~~~
-Type the following to start the services automatically on system startup:
+Mount the bricks:
-~~~
-chkconfig memcached on
-chkconfig glusterd on
-~~~
-
-### Gluster Volume Setup
-Now you need to determine whether you are going to use a partition or a loopback device
-for storage.
+```sh
+# mount -a
+```
-#### Partition Storage Setup
-If you are using a separate disk partition, please execute the following instructions
-to create a GlusterFS brick:
-
-~~~
-mkfs.xfs -i size=512 /dev/<disk partition>
-mkdir -p /export/brick
-~~~
+You can now create and start the GlusterFS volume.
+Make sure your hostname is in /etc/hosts or is DNS-resolvable.
-Add the following line to `/etc/fstab` to mount the storage automatically on system
-startup:
+```sh
+# gluster volume create myvolume replica 2 transport tcp `hostname`:/export/brick{1..4}/data force
+# gluster volume start myvolume
+```
-~~~
-/dev/<disk partition> /export/brick xfs inode64,noatime,nodiratime 0 0
-~~~
+Mount the GlusterFS volume:
-Now type the following to mount the storage:
-
-~~~
-mount -a
-~~~
-
-#### Loopback Storage Setup
-If you do not have a separate partition, please execute the following instructions
-to create a disk image as a file:
-
-~~~
-truncate -s 5GB /srv/swift-disk
-mkfs.xfs -i size=512 /srv/swift-disk
-mkdir -p /export/brick
-~~~
-
-Add the following line to `/etc/fstab` to mount the storage automatically on system
-startup:
-
-~~~
-/srv/swift-disk /export/brick xfs loop,inode64,noatime,nodiratime 0 0
-~~~
-
-Now type the following to mount the storage:
-
-~~~
-mount -a
-~~~
-
-### Create a GlusterFS Volume
-You now need to create a GlusterFS volume (make sure your hostname is in /etc/hosts or is DNS-resolvable)
-
-~~~
-mkdir /export/brick/b1
-gluster volume create myvolume `hostname`:/export/brick/b1
-gluster volume start myvolume
-~~~
+```sh
+# mkdir -p /mnt/gluster-object/myvolume
+# mount -t glusterfs `hostname`:myvolume /mnt/gluster-object/myvolume
+```
<a name="swift_setup" />
-## Gluster-Swift Setup
+## Setting up gluster-swift
-### Repository Setup on RHEL/CentOS
-Gluster-Swift requires OpenStack Swift's Havana release, which
-may not be available on some older operating systems. For RHEL/CentOS
-systems, please setup Red Hat RDO's repo by executing the following command:
+### Installing Openstack Swift (kilo version)
-~~~
-yum install -y http://rdo.fedorapeople.org/rdo-release.rpm
-~~~
+If on Ubuntu 16.04:
-### Download
-Download the latest Havana release RPMs from [launchpad.net downloads][]:
+```sh
+# apt install python-pip libffi-dev memcached
+# git clone https://github.com/openstack/swift; cd swift
+# git checkout -b kilo tags/kilo-eol
+# pip install -r ./requirements.txt
+# python setup.py install
+```
-### Install
-Install the RPM by executing the following:
+If on CentOS 7:
-~~~
-yum install -y <path to RPM>
-~~~
+```sh
+# yum install centos-release-openstack-kilo
+# yum install openstack-swift-*
+```
-### Enabling gluster-swift accross reboots
-Type the following to make sure gluster-swift is enabled at
-system startup:
+### Installing gluster-swift (kilo version)
-~~~
-chkconfig openstack-swift-proxy on
-chkconfig openstack-swift-account on
-chkconfig openstack-swift-container on
-chkconfig openstack-swift-object on
-~~~
+If on Ubuntu 16.04:
-#### Fedora 19 Adjustment
-Currently gluster-swift requires its processes to be run as `root`. You need to
-edit the `openstack-swift-*.service` files in
-`/etc/systemd/system/multi-user.target.wants` and change the `User` entry value
-to `root`.
+```sh
+# git clone https://github.com/gluster/gluster-swift; cd gluster-swift
+# pip install -r ./requirements.txt
+# python setup.py install
+```
-Then run the following command to reload the configuration:
+If on CentoOS 7:
-~~~
-systemctl --system daemon-reload
-~~~
+```sh
+# yum install epel-release
+# yum install python-scandir python-prettytable git
+# git clone https://github.com/gluster/gluster-swift; cd gluster-swift
+# python setup.py install
+```
-### Configuration
+### gluster-swift configuration files
As with OpenStack Swift, gluster-swift uses `/etc/swift` as the
directory containing the configuration files. You will need to base
the configuration files on the template files provided. On new
installations, the simplest way is to copy the `*.conf-gluster`
files to `*.conf` files as follows:
-~~~
-cd /etc/swift
-for tmpl in *.conf-gluster ; do cp ${tmpl} ${tmpl%.*}.conf; done
-~~~
+Copy conf files from `etc` directory in gluster-swift repo to
+`/etc/swift` and rename the template files.
-#### Generate Ring Files
-You now need to generate the ring files, which inform gluster-swift
-which GlusterFS volumes are accessible over the object
-storage interface. The format is
+```sh
+# mkdir -p /etc/swift/
+# cp etc/* /etc/swift/
+# cd /etc/swift
+# for tmpl in *.conf-gluster ; do cp ${tmpl} ${tmpl%.*}.conf; done
+```
-~~~
-gluster-swift-gen-builders [VOLUME] [VOLUME...]
-~~~
+### Export GlusterFS volumes over gluster-swift
+
+You now need to generate the ring files, which informs gluster-swift
+which GlusterFS volumes are accessible over the object storage interface.
+The format is:
+
+```sh
+# gluster-swift-gen-builders [VOLUME] [VOLUME...]
+```
Where *VOLUME* is the name of the GlusterFS volume which you would
like to access over gluster-swift.
@@ -199,20 +161,16 @@ like to access over gluster-swift.
Let's now expose the GlusterFS volume called `myvolume` you created above
by executing the following command:
-~~~
-cd /etc/swift
-/usr/bin/gluster-swift-gen-builders myvolume
-~~~
+```sh
+# gluster-swift-gen-builders myvolume
+```
### Start gluster-swift
Use the following commands to start gluster-swift:
-~~~
-service openstack-swift-object start
-service openstack-swift-container start
-service openstack-swift-account start
-service openstack-swift-proxy start
-~~~
+```sh
+# swift-init main start
+```
<a name="using_swift" />
## Using gluster-swift
@@ -220,41 +178,41 @@ service openstack-swift-proxy start
### Create a container
Create a container using the following command:
-~~~
-curl -v -X PUT http://localhost:8080/v1/AUTH_myvolume/mycontainer
-~~~
+```sh
+# curl -i -X PUT http://localhost:8080/v1/AUTH_myvolume/mycontainer
+```
It should return `HTTP/1.1 201 Created` on a successful creation. You can
also confirm that the container has been created by inspecting the GlusterFS
volume:
-~~~
-ls /mnt/gluster-object/myvolume
-~~~
+```sh
+# ls /mnt/gluster-object/myvolume
+```
#### Create an object
You can now place an object in the container you have just created:
-~~~
-echo "Hello World" > mytestfile
-curl -v -X PUT -T mytestfile http://localhost:8080/v1/AUTH_myvolume/mycontainer/mytestfile
-~~~
+```sh
+# echo "Hello World" > mytestfile
+# curl -i -X PUT -T mytestfile http://localhost:8080/v1/AUTH_myvolume/mycontainer/mytestfile
+```
To confirm that the object has been written correctly, you can compare the
test file with the object you created:
-~~~
-cat /mnt/gluster-object/myvolume/mycontainer/mytestfile
-~~~
+```sh
+# cat /mnt/gluster-object/myvolume/mycontainer/mytestfile
+```
#### Request the object
Now you can retreive the object and inspect its contents using the
following commands:
-~~~
-curl -v -X GET -o newfile http://localhost:8080/v1/AUTH_myvolume/mycontainer/mytestfile
-cat newfile
-~~~
+```sh
+# curl -i -X GET -o newfile http://localhost:8080/v1/AUTH_myvolume/mycontainer/mytestfile
+# cat newfile
+```
<a name="what_now" />
## What now?
@@ -263,11 +221,10 @@ For more information, please visit the following links:
* [Authentication Services Start Guide][]
* [GlusterFS Quick Start Guide][]
* [OpenStack Swift API][]
+* [Accessing over Amazon S3 API][]
+
[GlusterFS Quick Start Guide]: http://www.gluster.org/community/documentation/index.php/QuickStart
[OpenStack Swift API]: http://docs.openstack.org/api/openstack-object-storage/1.0/content/
-[Jenkins]: http://jenkins-ci.org
[Authentication Services Start Guide]: auth_guide.md
-[EPEL]: https://fedoraproject.org/wiki/EPEL
-[launchpad.net downloads]: http://launchpad.net/gluster-swift/havana/1.10.0-2
-
+[Accessing over Amazon S3 API]: s3.md