Update documentation

twindb · Nov 3, 2016 · 282a370 · 282a370
1 parent cce3cd9
commit 282a370
Show file tree

Hide file tree

Showing 6 changed files with 214 additions and 56 deletions.
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -15,7 +15,7 @@ Types of Contributions
 Report Bugs
 ~~~~~~~~~~~
 
-Report bugs at https://github.com/twindb/twindb_backup/issues.
+Report bugs at https://github.com/twindb/backup/issues.
 
 If you are reporting a bug, please include:
 
@@ -45,7 +45,7 @@ articles, and such.
 Submit Feedback
 ~~~~~~~~~~~~~~~
 
-The best way to send feedback is to file an issue at https://github.com/twindb/twindb_backup/issues.
+The best way to send feedback is to file an issue at https://github.com/twindb/backup/issues.
 
 If you are proposing a feature:
 
@@ -57,12 +57,12 @@ If you are proposing a feature:
 Get Started!
 ------------
 
-Ready to contribute? Here's how to set up `twindb_backup` for local development.
+Ready to contribute? Here's how to set up TwinDB Backup for local development.
 
-1. Fork the `twindb_backup` repo on GitHub.
+1. Fork the TwinDB Backup repo on GitHub.
 2. Clone your fork locally::
 
-    $ git clone git@github.com:your_name_here/twindb_backup.git
+    $ git clone git@github.com:your_name_here/backup.git twindb_backup
 
 3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development::
 
@@ -78,9 +78,7 @@ Ready to contribute? Here's how to set up `twindb_backup` for local development.
 
 5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox::
 
-    $ flake8 twindb_backup tests
-    $ python setup.py test or py.test
-    $ tox
+    $ make test-all
 
    To get flake8 and tox, just pip install them into your virtualenv.
 
@@ -97,18 +95,7 @@ Pull Request Guidelines
 
 Before you submit a pull request, check that it meets these guidelines:
 
-1. The pull request should include tests.
-2. If the pull request adds functionality, the docs should be updated. Put
-   your new functionality into a function with a docstring, and add the
-   feature to the list in README.rst.
-3. The pull request should work for Python 2.6, 2.7, 3.3, 3.4 and 3.5, and for PyPy. Check
-   https://travis-ci.org/twindb/twindb_backup/pull_requests
-   and make sure that the tests pass for all supported Python versions.
-
-Tips
-----
-
-To run a subset of tests::
-
-$ py.test tests.test_twindb_backup
-
+- The pull request should include tests.
+- If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
+- The pull request should work for Python 2.6 and 2.7.
+- Check https://travis-ci.org/twindb/backup/pull_requests and make sure that the tests pass for all supported Python versions.
diff --git a/HISTORY.rst b/HISTORY.rst
@@ -2,7 +2,6 @@
 History
 =======
 
-2.0.0 (2016-09-28)
-------------------
+See `GitHub commits history`_.
 
-* First release on PyPI.
+.. _GitHub commits history: https://github.com/twindb/backup/commits/master
diff --git a/README.rst b/README.rst
@@ -1,21 +1,14 @@
-===============================
+=============
 TwinDB Backup
-===============================
+=============
 
 
-.. image:: https://img.shields.io/pypi/v/twindb_backup.svg
-        :target: https://pypi.python.org/pypi/twindb_backup
+.. image:: https://img.shields.io/travis/twindb/backup.svg
+    :target: https://travis-ci.org/twindb/backup
 
-.. image:: https://img.shields.io/travis/twindb/twindb_backup.svg
-        :target: https://travis-ci.org/twindb/twindb_backup
-
-.. image:: https://readthedocs.org/projects/twindb-backup/badge/?version=latest
-        :target: https://twindb-backup.readthedocs.io/en/latest/?badge=latest
-        :alt: Documentation Status
-
-.. image:: https://pyup.io/repos/github/twindb/twindb_backup/shield.svg
-     :target: https://pyup.io/repos/github/twindb/twindb_backup/
-     :alt: Updates
+.. image:: https://readthedocs.org/projects/twindb-backup/badge/?version=master
+    :target: https://twindb-backup.readthedocs.io/en/master/?badge=master
+    :alt: Documentation Status
 
 
 TwinDB Backup tool for files, MySQL et al.
@@ -28,13 +21,53 @@ TwinDB Backup tool for files, MySQL et al.
 Features
 --------
 
-* TODO
+**twindb-backup** takes backups of:
+
+- Files and directories
+- MySQL with XtraBackup
+
+**twindb-backup** store backups on:
+
+- Remote SSH server
+- Amazon sS3
+- Optionally save local copy
+
+Other features:
+
+- Retention policy defines how many hourly/daily/weekly/monthly/yearly copies to keep
+- Separate retention policy for remote and local backup copies
+- Enables/disables ``wsrep_desync`` for Percona Cluster backups
+- Email notifications
+- cron configuration comes with a package
+
+
+How do I get set up?
+~~~~~~~~~~~~~~~~~~~~
+
+**twindb-backup** is distributed via the YUM repository.
+Check instructions_ on how to set up the repository.
+Once the repo is configured install the ``twindb-backup`` package.
+
+.. code-block:: console
+
+    # yum install twindb-backup
+
+
+
+Configuration
+~~~~~~~~~~~~~
+Configuration is stored in ``/etc/twindb/twindb-backup.cfg``. Configuration options are self-explanatory.
+We will describe specifics in the `wiki page`_ if any questions arrive.
+
+The rpm package installs a cron job, so no additional configuration is required.
+
 
 Credits
----------
+-------
 
 This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.
 
 .. _Cookiecutter: https://github.com/audreyr/cookiecutter
 .. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
-
+.. _instructions: https://twindb.com/twindb-software-repository/
+.. _wiki page: https://github.com/twindb/backup/wiki
diff --git a/docs/index.rst b/docs/index.rst
@@ -4,7 +4,7 @@
    contain the root `toctree` directive.
 
 Welcome to TwinDB Backup's documentation!
-======================================
+=========================================
 
 Contents:
 
@@ -15,7 +15,8 @@ Contents:
    installation
    usage
    contributing
-   authorshistory
+   authors
+   history
 
 Indices and tables
 ==================

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -12,15 +12,10 @@ To install TwinDB Backup, run this command in your terminal:
 
 .. code-block:: console
 
-    $ pip install twindb_backup
+    # rpm -Uhv https://twindb.com/twindb-release-latest.noarch.rpm
+    # yum install twindb-backup
 
-This is the preferred method to install TwinDB Backup, as it will always install the most recent stable release. 
-
-If you don't have `pip`_ installed, this `Python installation guide`_ can guide
-you through the process.
-
-.. _pip: https://pip.pypa.io
-.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
+This is the preferred method to install TwinDB Backup, as it will always install the most recent stable release.
 
 
 From sources
@@ -44,7 +39,7 @@ Once you have a copy of the source, you can install it with:
 
 .. code-block:: console
 
-    $ python setup.py install
+    $ make install
 
 
 .. _Github repo: https://github.com/twindb/twindb_backup

diff --git a/docs/usage.rst b/docs/usage.rst
@@ -2,6 +2,149 @@
 Usage
 =====
 
-To use TwinDB Backup in a project::
+Configuration
+-------------
 
-    import twindb_backup
+Once the ``twindb-backup`` package is installed you need to edit configuration file ``/etc/twindb/twindb-backup.cfg``.
+
+Let's review each configuration section.
+
+Source
+~~~~~~
+
+``[source]`` section defines what to backup.
+
+twindb-backup supports backing up local directories and MySQL database.
+
+
+In ``backup_dirs`` you specify which directories to backup. Each directory is separated by a white space.
+
+
+``backup_mysql`` tells whether the tool backups MySQL or not.
+
+::
+
+    [source]
+    backup_dirs=/etc /root /home
+    backup_mysql=no
+
+Destination
+~~~~~~~~~~~
+
+``[destination]`` specifies where to store backup copies.
+
+``backup_destination`` can be either ``ssh`` (if you want to store backups on a remote SSh server)
+or ``s3`` (if you want to store backups in Amazon S3).
+
+In the optional ``keep_local_path`` you can specify a local path where the tool will store a local copy of the backup.
+It's useful if you want to stream a MySQL backup to S3 and would like to keep a local copy as well.
+
+::
+
+    [destination]
+    backup_destination=ssh
+    keep_local_path=/var/backup/local
+
+Amazon S3
+~~~~~~~~~
+
+In ``[s3]`` section you specify Amazon credentials as well as an S3 bucked where to store backups.
+
+::
+
+    [s3]
+
+    # S3 destination settings
+
+    AWS_ACCESS_KEY_ID=XXXXX
+    AWS_SECRET_ACCESS_KEY=YYYYY
+    AWS_DEFAULT_REGION=us-east-1
+    BUCKET=twindb-backups
+
+SSH Settings
+~~~~~~~~~~~~
+
+If your backup destination is an SSH server, you specify ssh parameters in ``[ssh]`` section.
+It is assumed you configured `SSH keys authentication`_. It will not work if you need to enter a password to login to ``backup_host``.
+
+::
+
+    [ssh]
+
+    backup_host=127.0.0.1
+    ssh_user=root
+    backup_dir=/tmp/backup
+
+
+MySQL
+~~~~~
+
+XtraBackup needs to connect to MySQL. In ``[mysql]`` section you specify a defaults file with user and password.
+
+::
+
+    [mysql]
+    mysql_defaults_file=/etc/twindb/my.cnf
+
+
+Retention Policy
+~~~~~~~~~~~~~~~~
+
+In ``[retention]`` section you specify how many copies you want to keep on the remote storage (s3 or ssh).
+
+::
+
+    [retention]
+    hourly_copies=24
+    daily_copies=7
+    weekly_copies=4
+    monthly_copies=12
+    yearly_copies=3
+
+
+Local Retention Policy
+~~~~~~~~~~~~~~~~~~~~~~
+
+if ``keep_local_path`` is defined in Destination_ the tool will apply ``[retention_local]`` on the local copies.
+
+::
+
+    [retention_local]
+    hourly_copies=1
+    daily_copies=1
+    weekly_copies=0
+    monthly_copies=0
+    yearly_copies=0
+
+Running Intervals
+~~~~~~~~~~~~~~~~~
+
+By default **twindb-backup** will run `hourly`, `daily`, `weekly`, `monthly` and `yearly`.
+If you would like to skip some runs ``[intervals]`` section is the right place to do so.
+
+::
+
+    [intervals]
+    run_hourly=yes
+    run_daily=yes
+    run_weekly=yes
+    run_monthly=yes
+    run_yearly=yes
+
+
+Email notification
+------------------
+The RPM package installs a cron job. If a backup job fails it will send standard error output to the specified email.
+The email address is specified in the cron configuration file ``/etc/cron.d/twindb-backup``.
+
+::
+
+    MAILTO=nagios@twindb.com
+    @hourly  root twindb-backup backup hourly
+    @daily   root twindb-backup backup daily
+    @weekly  root twindb-backup backup weekly
+    @monthly root twindb-backup backup monthly
+    @yearly  root twindb-backup backup yearly
+
+
+.. _SSH keys authentication: https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/6/html/Deployment_Guide/s2-ssh-configuration-keypairs.html