Commits

Mikhail Korobov committed 51304f7

Improved docs

Comments (0)

Files changed (4)

 managing django projects on Debian servers. License is MIT.
 
 Please read the docs for more info.
-
-
-
-6. You should be able to run ``fab full_deploy`` from project root now.
-
-   .. warning::
-
-      django-fab-deploy takes over apache and reconfigures it so if
-      there are other sites not managed by django-fab-deploy they will probably
-      become unaccessible. In particular, django-fab-deploy deletes 'default'
-      site and removes 'ports.conf' so apache is not longer listening to 80 port.
-
-   Run it. 'stage' server will be configured: necessary system and python
-   packages will be installed, apache and ngnix will be configured,
-   virtualenv will be created and project will be on the server.
-   If you want to deploy on prod server, run ``fab prod full_deploy``.
-
-   Project sources will be available under ``~/src/<instance_name>``, virtualenv
-   will be placed in ``~/envs/<instance_name>``.
-
-
-7. TODO: this step should be eliminated?
-   Finish some tasks that were not handled by django-fab-tools:
-
-   a) For now mysql should be installed manually::
-
-        $ aptitude install mysql-server
-
-   b) Then you should create a DB using mysql shell::
-
-        CREATE DATABASE db_name DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci;
-
-   c) Then perform the 'syncdb' step on your server::
-
-        $ ./manage syncdb
-
-   d) Then run 'syncdb' and 'migrate' (from local machine)::
-
-        $ fab syncdb migrate
-
-   e) Django session tables must be MyISAM for performance reasons (InnoDB will
-      try to sort session keys ).
-      If the default engine is InnoDB then the following command should be
-      performed in mysql shell::
-
-        alter table django_session engine=myisam;
-
-   f) Configuring the email server::
-
-        $ dpkg-reconfigure exim4-config
-
-9. You project should be now up and running.
-
-
-Some common tasks (dig into source code for more)
-=================================================
-
-1. Deploy changes on default server::
-
-        $ fab push
-
-2. Deploy changes on another server, update pip requirements and
-   perform migrations::
-
-        $ fab prod push:pip_update,migrate
-
-3. Update requirements specified in reqs/active.txt::
-
-        $ fab pip_update
-
-4. Update requirements specified in reqs/my_apps.txt::
-
-        $ fab pip_update:my_apps
-
-5. Remotely change hg branch::
-
-        $ fab up:my_branch
-
-TODO: provide complete list of commands
-
 Prerequisites
 -------------
 
-1. Clean Debian Lenny (Debian Squeeze will be supported soon) server or
+1. Clean Debian Lenny (Debian Squeeze supported is planned) server or
    VPS with root ssh access;
 2. working ssh key authentication;
 3. django project stored in mercurial VCS.
        $ pip install jinja2
        $ pip install -e git+git://github.com/bitprophet/fabric.git#egg=Fabric-dev
 
-2. Make sure your project match this structure::
-
-        my_project
-            ...
-            config_templates <- this folder should be copied from django-fab-deploy, see below
-                ...
-
-            reqs             <- a folder with project's pip requirement files
-                all.txt      <- main requirements file, list all requirements in this file
-                active.txt   <- put recently modified requirements here
-                ...          <- you can provide extra files and include them with '-r' syntax in e.g. all.txt
-
-            fabfile.py       <- your project's Fabric deployment script, see below
-            config.py        <- this file should be included in settings.py and ignored in .hgignore
-            config.server.py <- this is a production django config template, see below
-            settings.py
-            manage.py
-
-   ``config.py`` trick is also known as ``local_settings.py``
-   (make sure config.py is ignored in your .hgignore).
-
-3. Create ``fabfile.py`` at project root. It should provide one or more
-   function putting server details into Fabric environment. Project-specific
-   scripts can also be put into fabfile. Example::
+2. Create :file:`fabfile.py` at project root. It should provide one or more
+   function putting server details into Fabric environment. Otherwise it's just
+   a standart Fabric's fabfile: project-specific scripts can also be put here.
+   Example::
 
         # my_project/fabfile.py
         from fabric.api import *
        and ``INSTANCE_NAME`` equals to ``env.user``. Look at :doc:`fabfile`
        for more details.
 
-4. Copy 'config_templates' folder from django-fab-deploy to your project root.
+3. Copy ``config_templates`` folder from django-fab-deploy to your project root.
 
    .. note::
 
 
        {{ variables }} can be used in config templates. They will be
        replaced with values from ``env.conf`` on server.
-       This also apply for ``config.server.py`` file.
+       This also apply for :file:`config.server.py` file.
 
-5. Create config.server.py. Example::
+4. Create :file:`config.server.py` at project root. Example::
 
         # my_project/config.server.py
         # config file for environment-specific settings
         }
         MEDIA_URL = 'http://{{ SERVER_NAME }}/static/'
 
+   Then create :file:`config.py` for development.
+   Import config in project's :file:`settings.py`::
+
+       # Django settings for my_project project.
+       # ...
+       from config import *
+       # ...
+
+   ``config.py`` trick is also known as ``local_settings.py``
+   (make sure ``config.py`` is ignored in your ``.hgignore``).
+
+
+5. Create ``reqs`` folder inside a project root. This folder should contain
+   text files with `pip requirements <http://pip.openplans.org/requirement-format.html>`_.
+
+   One file is special: :file:`reqs/all.txt`. This is the main requirements
+   file. List all project requirements here one-by-one or (preferrable) by
+   including other requirement files using "-r" syntax).
+
+
+The project should look like that after finishing steps 1-5::
+
+    my_project
+        ...
+        config_templates <- this folder should be copied from django-fab-deploy
+            apache.config
+            django_wsgi.py
+            hgrc
+            nginx.config
+
+        reqs             <- a folder with project's pip requirement files
+            all.txt      <- main requirements file, list all requirements in this file
+            active.txt   <- put recently modified requirements here
+            ...          <- you can provide extra files and include them with '-r' syntax in e.g. all.txt
+
+        fabfile.py       <- your project's Fabric deployment script
+        config.py        <- this file should be included in settings.py and ignored in .hgignore
+        config.server.py <- this is a production django config template
+        settings.py
+        manage.py
+
 The project is now ready to be deployed.
 
 Prepare the server
 ------------------
 
-1. If there is no linux account for ``env.user`` (from fabfile.py)
+1. If there is no linux account for ``env.user``
    then add a new linux server user, manually or using
 
    ::
        Fabric commands should be executed in shell from the project root
        on local machine (not from the python console, not on server shell).
 
+   SSH keys for other developers can be added at any time::
+
+       fab ssh_add_key:"/home/kmike/coworker-keys/ivan.id_dsa.pub"
+
 2. Setup the database. django-fab-deploy can install mysql and create empty
    DB for the project::
 
-       $ fab mysql_install
-       $ fab mysql_create_db
+       fab mysql_install
+       fab mysql_create_db
 
    :func:`mysql_install<fab_deploy.mysql.mysql_install>` does
    nothing if mysql is already installed on server. Otherwise it installs
    ``env.user`` by default).
 
 
-If you feel brave you can now run ``fab full_deploy`` from the project root
-and get a working django site.
+3. If you feel brave you can now run ``fab full_deploy`` from the project root
+   and get a working django site.
+
+   Necessary system and python packages will be installed, apache and ngnix
+   will be configured, virtualenv will be created and the project will be
+   uploaded to the server.
+
+   Project sources will be available under ``~/src/<instance_name>``, virtualenv
+   will be placed in ``~/envs/<instance_name>``.
 
    .. warning::
 
       django-fab-deploy deletes 'default' apache and nginx sites and
-      takes over 'ports.conf' so apache is not longer listening to 80 port.
+      takes over 'ports.conf' so apache is no longer listening to 80 port.
 
       If there are other sites on server (not managed by django-fab-deploy)
-      they may become unaccessible.
+      they may become unaccessible due to these changes.
 
-
-Working with site
------------------
   `nginx`_ in front as a reverse proxy;
 
 Several projects can be deployed on the same VPS using django-fab-deploy.
-One project can be deployed on several servers. Projects are isolated
-with virtualenv.
+One project can be deployed on several servers. Projects are isolated and
+deployments are repeatable.
 
 .. _virtualenv: http://virtualenv.openplans.org/
 .. _pip: http://pip.openplans.org/
    :maxdepth: 2
 
    guide
-   overview
    fabfile
+   related
 
 .. note::
 
     django-fab-deploy is still at early stages of development and API may
     change in future. However each version should work fine and most of them
-    were used to deploy at least one production site.
+    were used to deploy production sites.
 
 
 License
+Related work
+============
+
+There are great projects aiming the same goal, including
+
+* `woven`_ : quite similar, targets mainly Ubuntu, have more deployment options;
+* `silverlining`_ : not tied to django and even python, targets Ubuntu,
+  quite sophisticated.
+
+.. _silverlining: https://bitbucket.org/ianb/silverlining/src
+.. _woven: https://github.com/bretth/woven
+
+django-fab-deploy targets Debian, have smaller codebase (x5..x10 less sloc),
+provides less features and thus is arguably easier to understand.