From 51f1c002f07b164bd75a890271125cf6efa4889f Mon Sep 17 00:00:00 2001 From: Shirisha Gaddi Date: Tue, 4 Oct 2016 17:23:15 +0530 Subject: [PATCH] Added documentation - features, installation, setup and list of all functions --- docs/source/commands.rst | 178 ++++++++++++++++++++++++++++++++++ docs/source/conf.py | 2 +- docs/source/configuration.rst | 21 ++++ docs/source/features.rst | 19 ++++ docs/source/index.rst | 45 +++++++-- docs/source/installation.rst | 16 +++ 6 files changed, 272 insertions(+), 9 deletions(-) create mode 100644 docs/source/commands.rst create mode 100644 docs/source/configuration.rst create mode 100644 docs/source/features.rst create mode 100644 docs/source/installation.rst diff --git a/docs/source/commands.rst b/docs/source/commands.rst new file mode 100644 index 0000000..5de32f7 --- /dev/null +++ b/docs/source/commands.rst @@ -0,0 +1,178 @@ +Commands +=========== + +Usage +------- + + .. code-block:: python + + fab + + + **List Commands** - shows the list of all available fab commands + + + .. code-block:: python + + fab -l + + +Install Requirements +---------------------- + +* To install the requirements on your local system: + + .. code-block:: python + + fab run_local activate_env_install_requirements + + (or) + + fab activate_env_install_requirements + +* To install the requirements on your remote staging servers: + + .. code-block:: python + + fab run_stage activate_env_install_requirements + +* To install the requirements on your remote live servers: + + .. code-block:: python + + fab run_live activate_env_install_requirements + + +Rsync project to remote server(stage/live) +--------------------------------------------- + +To rsync project local files to remote destination server - + + * with settings file - + + .. code-block:: python + + fab rsync_with_settings + + * without settings file - + + .. code-block:: python + + fab rsync_without_settings + + +Deploy To Server +------------------ + +This commands copy local project files to destination(stage/live) servers, installs requirements, applies migrations and finally runs uWSGI server(both in debug and deployment modes) + + .. code-block:: python + + fab deploy_to_server + + By default, this command rsyncs project files without settings file and runs touch command for project uwsgi file under /etc/uwsgi/vassals/ folder. + + * To rsync with settings file and to run uwsgi in debug mode: + + .. code-block:: python + + fab deploy_to_server:sync_with_setting='true',debug='true' + + + .. note:: + + It automatically creates project_root, env in server if not exists + + +Local database backup +----------------------- + + .. code-block:: python + + fab take_local_backup + + +Server database backup +------------------------ + + .. code-block:: python + + fab take_server_backup + + +Restore Server database to Local +--------------------------------- + +.. code-block:: python + + fab take_server_backup + fab restore_to_local + + +Reset Local database +----------------------- + + .. code-block:: python + + fab reset_local_db + + +Reset Server database +----------------------- + + .. code-block:: python + + fab reset_server_db + + +Run Management Commands +-------------------------- + +This function is used to run management commands - + + .. code-block:: python + + fab manage_py: + + * To apply migrations + + .. code-block:: python + + fab migrate + + * Execute collect static + + .. code-block:: python + + fab collect_static + + * Rebuild search index + + .. code-block:: python + + fab rebuild_index + + * To restart celery in remote servers + + .. code-block:: python + + fab restart_celery + + * To restart supervisorctl in remote servers + + .. code-block:: python + + fab restart_supervisior + + * To restart uwsgi in remote servers + + .. code-block:: python + + fab restart_uwsgi + + * To restart remote servers + + .. code-block:: python + + fab restart_server + diff --git a/docs/source/conf.py b/docs/source/conf.py index e9c9550..3dff6ee 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -119,7 +119,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'alabaster' +html_theme = 'sphinx_rtd_theme' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst new file mode 100644 index 0000000..4bf423b --- /dev/null +++ b/docs/source/configuration.rst @@ -0,0 +1,21 @@ +Setup +========= + +* First, create an YAML file similar to `sample_config.yaml`_ and fill the configuration details. + +* Next, create a file named :code:`fabfile.py` in your project directory and import all functions(fab commands/tasks) from `django_spanner`. + +* Finally, call the :code:`setup()` function with your configuration yaml file path. + + +**Here is an example fabfile** - + +.. code-block:: python + + # fabfile.py + from django_spanner.commands import * + setup("config_file_name.yaml") + + +.. _`sample_config.yaml`: https://github.com/MicroPyramid/django-spanner/blob/master/django_spanner/sample_config.yaml + diff --git a/docs/source/features.rst b/docs/source/features.rst new file mode 100644 index 0000000..42c5b9e --- /dev/null +++ b/docs/source/features.rst @@ -0,0 +1,19 @@ +Features +=========== + + * Install requirements in a virtualenv. + * Migrate database. + * Execute any management command. + * Rsync files to destination server(stage/live) with and without settings file. + * Deploy the django application to server(Installs requirements, migrates database, rsync files, runs uwsgi server). + * Take database backups(server backups as well as local). + * Restore local and server databases. + * Reset local and server databases. + * Restart server, celery, supervisor, uwsgi. + * Rebuild index, collect static. + + +.. note:: + + You can execute all these commands in local as well as remote servers. + diff --git a/docs/source/index.rst b/docs/source/index.rst index 23ac7bd..c67294b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,20 +3,49 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to django_spanner's documentation! -========================================== -Contents: +Django Spanner +================ + +Django Spanner is a simple package used to deploy and manage `Django`_ applications. Django Spanner is a set of commands used to deploy and manage django projects. It internally uses `Fabric`_. This can also be called as **Deploying Django with Fabric**. + +* You can use this to deploy & manage any django application with just few configurations. Configure once and run many times. + +* As well as you can deploy & manage single django application on multiple remote servers (multiple staging servers, multiple live servers). You can specify different configuration for each type of server (stage/live) like here `sample config file`_ + +* Also used to manage local django project to install requirements, run make migrations, migrate, take database backups and many more... + + +This package is developed by `MicroPyramid`_ team. Please refer the `github repository`_ for the django-spanner source code. It's free and open source. + + +Github Repository +******************** + + Django Spanner - `https://github.com/MicroPyramid/django-spanner`_ + + +Contents +---------- .. toctree:: :maxdepth: 2 + features + installation + configuration + commands + + +.. _`Django`: https://www.djangoproject.com/ + +.. _`Fabric`: http://www.fabfile.org/ + +.. _`MicroPyramid`: https://micropyramid.com/ +.. _`github repository`: https://github.com/MicroPyramid/django-spanner -Indices and tables -================== +.. _`https://github.com/MicroPyramid/django-spanner`: https://github.com/MicroPyramid/django-spanner -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +.. _`sample config file`: https://github.com/MicroPyramid/django-spanner/blob/master/django_spanner/sample_config.yaml diff --git a/docs/source/installation.rst b/docs/source/installation.rst new file mode 100644 index 0000000..3d484a2 --- /dev/null +++ b/docs/source/installation.rst @@ -0,0 +1,16 @@ +Installation +============= + +The recommended way to install the django-spanner into a virtualenv using pip:: + + pip install django-spanner + + +Or, install using the latest version from GitHub:: + + git clone https://github.com/MicroPyramid/django-spanner.git + + cd django_spanner + + python setup.py install +