Commits

Mikhail Korobov committed 7b07886

Docs for new features

Comments (0)

Files changed (6)

 CHANGES
 =======
 
+0.6 (2011-03-11)
+----------------
+- custom project layouts support (thanks Vladimir Mihailenco):
+  standard project layout is no longer required; if the project has
+  pip requirements file(s) and a folder with web server config templates
+  it should be possible to use django-fab-deploy for deployment;
+- git uploads support (thanks Vladimir Mihailenco);
+- lxml installation is fixed;
+- sqlite deployments are supported (for testing purposes).
+
+If you are planning to migrate to non-default project layout, update the
+config templates:
+
+* in :file:`apache.config` and :file:`nginx.config`:
+  replace ``{{ SRC_DIR }}`` with ``{{ PROJECT_DIR }}``
+* in :file:`django_wsgi.py`: replace ``{{ SRC_DIR }}`` with
+  ``{{ PROJECT_DIR }}`` and make sure DJANGO_SETTINGS_MODULE doesn't
+  contain INSTANCE_NAME::
+
+      os.environ['DJANGO_SETTINGS_MODULE'] = 'settings'
+
+
 0.5.1 (2011-02-25)
 ------------------
 - Python 2.5 support for local machine (it was always supported on servers).
 # built documents.
 #
 # The short X.Y version.
-version = '0.5'
+version = '0.6'
 # The full version, including alpha/beta/rc tags.
-release = '0.5'
+release = '0.6'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/custom_layouts.rst

+Custom project layouts
+======================
+
+:doc:`guide` describes standard project layout::
+
+    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
+
+django-fab-deploy does not enforce this layout. Requirements handling,
+config templates placement, local settings file names and project source
+folder can be customized using these options:
+
+* :attr:`env.conf.PROJECT_PATH`
+* :attr:`env.conf.LOCAL_CONFIG`
+* :attr:`env.conf.REMOTE_CONFIG_TEMPLATE`
+* :attr:`env.conf.CONFIG_TEMPLATES_PATHS`
+* :attr:`env.conf.PIP_REQUIREMENTS_PATH`
+* :attr:`env.conf.PIP_REQUIREMENTS`
+
+Example
+-------
+
+Let's configure django-fab-deploy to use the following layout::
+
+    my_project
+        hosting                 <- a folder with server configs
+            staging             <- custom configs for 'staging' server
+                apache.config   <- custom apache config for staging server
+
+            production          <- custom configs for 'production' server
+                apache.config
+                nginx.config
+
+            apache.config       <- default configs
+            django_wsgi.py
+            nginx.config
+
+        src                     <- django project source files
+            apps
+                ...
+
+            local_settings.py   <- local settings
+            stage_settings.py   <- local settings for staging server
+            prod_settings.py    <- local settings for production server
+
+            settings.py
+            manage.py
+
+        requirements.txt        <- single file with all pip requirements
+        fabfile.py              <- project's Fabric deployment script
+
+It uses subfolder for storing django project sources, single pip requirements
+file and different config templates for different servers in
+non-default locations.
+
+fabfile.py::
+
+    from fab_deploy import *
+
+    # common layout options
+    COMMON_OPTIONS = dict(
+        PROJECT_PATH = 'src',
+        LOCAL_CONFIG = 'local_settings.py',
+        PIP_REQUIREMENTS = 'requirements.txt',
+        PIP_REQUIREMENTS_PATH = '',
+    )
+
+    def staging():
+        env.hosts = ['user@staging.example.com']
+        env.conf = dict(
+            REMOTE_CONFIG_TEMPLATE = 'stage_settings.py',
+            CONFIG_TEMPLATES_PATHS = ['hosting/staging', 'hosting'],
+        )
+        env.conf.update(COMMON_OPTIONS)
+        update_env()
+
+    def production():
+        env.hosts = ['user@example.com']
+        env.conf = dict(
+            REMOTE_CONFIG_TEMPLATE = 'prod_settings.py',
+            CONFIG_TEMPLATES_PATHS = ['hosting/production', 'hosting'],
+        )
+        env.conf.update(COMMON_OPTIONS)
+        update_env()
+
     This option can be used to run different servers from different git
     branches.
 
+.. attribute:: env.conf.PROJECT_PATH
+
+    Path to django project (relative to repo root). Default is ''.
+
+.. attribute:: env.conf.LOCAL_CONFIG
+
+    Local django config file name. Default is 'config.py'. Common values
+    include 'local_settings.py' and 'settings_local.py'. This file should
+    be placed inside :attr:`env.conf.PROJECT_PATH`, imported from settings.py
+    and excluded from version control.
+
+    .. note::
+
+        Default value is not set to one of widely-used file names by default
+        (e.g. 'local_settings.py') in order to prevent potential data loss
+        during converting existing project to django-fab-deploy:
+        this file is overwritten on server during deployment process; it is
+        usually excluded from VCS and contains important information.
+
+.. attribute:: env.conf.REMOTE_CONFIG_TEMPLATE
+
+    The name of file with remote config template. Default is
+    'config.server.py'. This file should be placed inside
+    :attr:`env.conf.PROJECT_PATH`. It will become
+    :attr:`env.conf.LOCAL_CONFIG` on server.
+
+.. attribute:: env.conf.CONFIG_TEMPLATES_PATHS
+
+    An iterable with paths to web server and other config templates.
+    Default is ``['config_templates']``.
+
+.. attribute:: env.conf.PIP_REQUIREMENTS_PATH
+
+    Default is 'reqs'. This path is relative to repo root.
+
+.. attribute:: env.conf.PIP_REQUIREMENTS
+
+    The name of main requirements file. Requirements from it are installed
+    during deployment. Default is 'all.txt'.
+
 .. attribute:: env.conf.APACHE_PORT
 
     The port used by apache backend. It is managed automatically
         settings.py
         manage.py
 
+.. note::
+
+    django-fab-deploy does not enforce this layout; if it doesn't fit for some
+    reason, take a look at :doc:`custom_layouts`.
+
 The project is now ready to be deployed.
 
 Prepare the server
 .. _virtualenv: http://virtualenv.openplans.org/
 .. _pip: http://pip.openplans.org/
 .. _fabric: http://fabfile.org/
-.. _mercurial: http://mercurial.selenic.com/
 .. _Apache: http://httpd.apache.org/
 .. _mod_wsgi: http://code.google.com/p/modwsgi/
 .. _nginx: http://nginx.org/
    :maxdepth: 2
 
    guide
+   custom_layouts
    fabfile
    reference
    testing
 
    CHANGES
 
-.. note::
-
-    django-fab-deploy is still at early stages of development and API may
-    change in future.
-
-
 Bug tracker
 ===========
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.