Commits

Mikhail Korobov  committed 68ebfb4

Documentation improvements

  • Participants
  • Parent commits 06611db

Comments (0)

Files changed (5)

File docs/fabfile.rst

 
     Database password.
 
+.. attribute:: env.conf.DB_ROOT_PASSWORD
+
+    Database password for a 'root' user. django-fab-deploy will ask for
+    mysql root password when necessary if this option is not set.
+
+.. attribute:: env.conf.SUDO_USER
+
+    User with sudo privileges. It is 'root' by default.
+    Use :func:`create_sudo_linux_account <fab_deploy.system.create_sudo_linux_account>`
+    in order to create non-root sudoer.
+
 .. attribute:: env.conf.PROCESSES
 
     The number of mod_wsgi daemon processes. It is a good idea to set it
 
 .. autofunction:: fab_deploy.utils.inside_src
 
-.. autofunction:: fab_deploy.utils.run_as
+.. autofunction:: fab_deploy.utils.run_as_sudo

File docs/guide.rst

 
    .. note::
 
-       There are some defaults, e.g. :attr:`DB_NAME <env.conf.DB_NAME>`
+       There are some defaults, e.g. :attr:`DB_USER <env.conf.DB_USER>`
+       is 'root' by default, :attr:`DB_NAME <env.conf.DB_NAME>`
        equals to :attr:`INSTANCE_NAME <env.conf.INSTANCE_NAME>`,
        and :attr:`INSTANCE_NAME <env.conf.INSTANCE_NAME>` equals
        to username obtained from :attr:`env.hosts`.
 .. note::
 
     django-fab-deploy does not enforce this layout; if it doesn't fit for some
-    reason, take a look at :ref:`custom-project-layouts`.
+    reason (e.g. you prefer single pip requirements file or django
+    project in subfolder), take a look at :ref:`custom-project-layouts`.
 
 The project is now ready to be deployed.
 
        fab create_linux_account:"/home/kmike/.ssh/id_rsa.pub"
 
    You'll need the ssh public key.
-   :func:`create_linux_account<fab_deploy.system.create_linux_account>`
+   :func:`create_linux_account <fab_deploy.system.create_linux_account>`
    creates a new linux user and uploads provided ssh key. Test that ssh
    login is working::
 
        fab mysql_install
        fab mysql_create_db
 
-   :func:`mysql_install<fab_deploy.mysql.mysql_install>` does
+   :func:`mysql_install <fab_deploy.mysql.mysql_install>` does
    nothing if mysql is already installed on server. Otherwise it installs
-   mysql-server package and sets root password to :attr:`env.conf.DB_PASSWORD`.
+   mysql-server package and set root password to
+   :attr:`env.conf.DB_ROOT_PASSWORD`. If this option is empty, mysql_install
+   will ask for a password.
 
-   :func:`mysql_create_db<fab_deploy.mysql.mysql_create_db>` creates a new
+   :func:`mysql_create_db <fab_deploy.mysql.mysql_create_db>` creates a new
    empty database named :attr:`env.conf.DB_NAME` (it equals to
    :attr:`env.conf.INSTANCE_NAME` by default, which equals to
    the user from :attr:`env.hosts` by default).
+   :func:`mysql_create_db <fab_deploy.mysql.mysql_create_db>` will
+   ask for a mysql root password if :attr:`DB_USER <env.conf.DB_USER>`
+   is not 'root'.
 
    .. note::
 
-        If non-root DB user is used or the DB enging is not mysql then
-        you'd better create DB and grant necessary priveleges manually.
+        If the DB enging is not mysql then DB should be created manually now.
 
 
 4. If you feel brave you can now run ``fab full_deploy`` from the project root

File docs/reference.rst

 
 .. automodule:: fab_deploy.nginx
     :members:
-
-

File fab_deploy/system.py

 from fab_deploy import utils
 
 
-__all__ = ['create_linux_account', 'create_sudo_linux_account', 'ssh_add_key', 'install_sudo']
+__all__ = ['create_linux_account', 'create_sudo_linux_account',
+           'ssh_add_key', 'install_sudo']
 
 
 def prepare_server():
 
 @utils.run_as_sudo
 def create_linux_account(pub_key_file, username=None):
-    """ Creates linux account, setups ssh access and pip.conf file. """
+    """
+    Creates linux account, setups ssh access and pip.conf file.
+
+    Example::
+
+        fab create_linux_account:"/home/kmike/.ssh/id_rsa.pub"
+
+    """
     with open(os.path.normpath(pub_key_file), 'rt') as f:
         ssh_key = f.read()
 
 
 @utils.run_as('root')
 def create_sudo_linux_account(pub_key_file, username=None):
+    """ Creates linux account, setups ssh access and
+    adds the created user to sudoers. This command requires root ssh access. """
     username = username or env.conf.SUDO_USER
     if username == 'root':
         return

File fab_deploy/utils.py

 def run_as(user):
     """
     Decorator. Runs fabric command as specified user. It is most useful to
-    run commands that require root access to server::
-
-        from fabric.api import run
-        from fab_deploy.utils import run_as
-
-        @run_as('root')
-        def aptitude_update():
-            run('aptitude update')
-
+    run commands that require root access to server.
     """
     def decorator(func):
         @wraps(func)
     return decorator
 
 def run_as_sudo(func):
+    """
+    Decorator. By default all commands are executed as user without
+    sudo access for security reasons. Use this decorator to run fabric
+    command as user with sudo access (:attr:`env.conf.SUDO_USER`)::
+
+        from fabric.api import run
+        from fab_deploy import utils
+
+        @utils.run_as_sudo
+        def aptitude_update():
+            run('aptitude update')
+    """
     @wraps(func)
     def wrapper(*args, **kwargs):
         return run_as(env.conf.SUDO_USER)(func)(*args, **kwargs)