PageRenderTime 163ms CodeModel.GetById 81ms app.highlight 2ms RepoModel.GetById 78ms app.codeStats 0ms

/docs/django-quickstart.txt

https://bitbucket.org/ianb/silverlining/
Plain Text | 250 lines | 187 code | 63 blank | 0 comment | 0 complexity | 1b2b9c1c0330bd9da318c70d1a82bbc4 MD5 | raw file
  1Django Quickstart
  2=================
  3
  4This document describes how to get started with Silver Lining using
  5Django.
  6
  7Creating a Layout
  8-----------------
  9
 10First thing you have to do (after installing Silver Lining of course)
 11is create an environment for your new application.  Do that like::
 12
 13    $ silver init sampleapp
 14
 15This creates a directory ``sampleapp/`` with a basic layout.  The
 16first thing we'll do is set up version control for our project.
 17For the sake of documentation, imagine you go to `bitbucket
 18<http://bitbucket.org>`_ and create two new repositories, one called
 19``sampleapp`` and another called ``sampleapp-lib`` (and for the
 20examples we'll use the username ``USER``).
 21
 22We'll go into our new environment and use these::
 23
 24    $ cd sampleapp
 25    $ hg clone http://bitbucket.org/USER/sampleapp src/sampleapp
 26    $ rm -r lib/python/
 27    $ hg clone http://bitbucket.org/USER/sampleapp-lib lib/python
 28    $ mkdir lib/python/bin/
 29    $ echo "syntax: glob
 30    bin/python*
 31    bin/activate
 32    bin/activate_this.py
 33    bin/pip
 34    bin/easy_install*
 35    " > lib/python/.hgignore
 36    $ mv bin/* lib/python/bin/
 37    $ rmdir bin/
 38    $ ln -s lib/python/bin bin
 39
 40Now there is a basic layout setup, with all your libraries going into
 41the ``sampleapp-lib`` repository, and your main application in the
 42``sampleapp`` repository.
 43
 44Next we'll install Django::
 45
 46    $ source bin/activate
 47    $ pip install Django
 48
 49Then we'll set up a standard Django site::
 50
 51    $ cd src/sampleapp
 52    $ django-admin.py startproject sampleapp
 53
 54Also we'd like to be able to import this file.  It'd be nice if there
 55was a ``setup.py`` file, and we could run ``pip -e src/sampleapp``,
 56but ``django-admin.py`` doesn't create that itself.  Instead we'll get
 57that on the import path more manually with a ``.pth`` file::
 58
 59    $ echo "../../src/sampleapp" > lib/python/sampleapp.pth
 60
 61That files will cause ``../../src/sampleapp`` (relative to the .pth
 62file itself) to be on ``sys.path``, which means when you run ``from
 63sampleapp import settings`` (for example) it will know to find it in
 64``src/sampleapp/sampleapp/settings.py``.  Not all Django projects are
 65setup this way -- applications are often not in a namespace, for
 66example.  But I think it's simply good practice to keep code
 67partitioned into namespaces.
 68
 69Also there's the tricky ``$DJANGO_SETTINGS_MODULE`` that you might
 70have had problems with before.  We'll use the file
 71``lib/python/silvercustomize.py`` (which is imported everytime Python is
 72started) to make sure that is always set::
 73
 74    $ echo "import os
 75    os.environ['DJANGO_SETTINGS_MODULE'] = 'sampleapp.settings'
 76    " > lib/python/silvercustomize.py
 77
 78Also we have a file ``src/sampleapp/sampleapp/manage.py``, and that
 79file doesn't work *quite* how we'd like.  Instead we'll put a file
 80into ``bin/manage.py`` that does the same thing::
 81
 82    $ rm sampleapp/manage.py
 83    $ cd ../..
 84    $ echo '#!/usr/bin/env python
 85    from django.core.management import execute_manager
 86    from sampleapp import settings
 87    if __name__ == "__main__":
 88        execute_manager(settings)
 89    ' > bin/manage.py
 90    $ chmod +x bin/manage.py
 91
 92Now, if you were just using plain Django you'd do something like run
 93``python manage.py runserver``.  But we'll be using ``silver serve``
 94instead, which means we have to set up the two other files Silver
 95Lining needs: ``app.ini`` and the runner.  Here's a simple
 96``app.ini``::
 97
 98    $ echo '[production]
 99    app_name = sampleapp
100    runner = src/sampleapp/silver-runner.py
101    ' > src/sampleapp/silver-app.ini
102    $ rm app.ini
103    $ ln -s src/sampleapp/silver-app.ini app.ini
104
105The file *must* be in the "root" of your application, and named
106``app.ini``, but it's good to keep it in version control, so we set it
107up with a symlink.
108
109It also refers to a "runner", which is the Python file that loads up
110the WSGI application.  This looks about the same for any Django
111application, and we'll put it in ``src/sampleapp/silver-runner.py``::
112
113    $ echo 'import django.core.handlers.wsgi
114    application = django.core.handlers.wsgi.WSGIHandler()
115    ' > src/sampleapp/silver-runner.py
116
117Now if you want to run the application, you can::
118
119    $ silver serve .
120
121This will load it up on ``http://localhost:8080``, and serve up a
122boring page.  To do something interesting we'll want to use a
123database.
124
125Setting Up A Database
126---------------------
127
128At the moment the only good database to use is PostgreSQL with the
129PostGIS extensions.  Add this line to ``app.ini``::
130
131    service.postgis =
132
133This makes the database "available" to the application.  For
134development you still have to set it up yourself.  You should create a
135database ``sampleapp`` on your computer.
136
137Next, we'll need to change ``settings.py`` to use the new database
138configuration.  Here's the lines that you'll see::
139
140    DATABASE_ENGINE = ''           # 'postgresql_psycopg2', 'postgresql', 'mysql', 'sqlite3' or 'oracle'.
141    DATABASE_NAME = ''             # Or path to database file if using sqlite3.
142    DATABASE_USER = ''             # Not used with sqlite3.
143    DATABASE_PASSWORD = ''         # Not used with sqlite3.
144    DATABASE_HOST = ''             # Set to empty string for localhost. Not used with sqlite3.
145    DATABASE_PORT = ''             # Set to empty string for default. Not used with sqlite3.
146
147First add this to the top of the file::
148
149    import os
150
151Then you'll change those lines to::
152
153    DATABASE_ENGINE = 'postgresql_psycopg2'
154    DATABASE_NAME = os.environ['CONFIG_PG_DBNAME']
155    DATABASE_USER = os.environ['CONFIG_PG_USER']
156    DATABASE_PASSWORD = os.environ['CONFIG_PG_PASSWORD']
157    DATABASE_HOST = os.environ['CONFIG_PG_HOST']
158    DATABASE_PORT = ''
159
160Now we can create all the default tables::
161
162    $ manage.py syncdb
163    Creating table auth_permission
164    Creating table auth_group
165    Creating table auth_user
166    Creating table auth_message
167    Creating table django_content_type
168    Creating table django_session
169    Creating table django_site
170    ...
171
172Now we have an empty project that doesn't do anything.  Let's make it
173do a little something (this is all really based on `the Django
174tutorial <http://docs.djangoproject.com/en/dev/intro/tutorial01/>`_).
175
176::
177
178    $ manage.py startapp polls
179
180Django magically knows to put the code in
181``src/sampleapp/sampleapp/polls/`` -- we'll setup the model in
182``src/sampleapp/sampleapp/polls/models.py``::
183
184    from django.db import models
185
186    class Poll(models.Model):
187        question = models.CharField(max_length=200)
188        pub_date = models.DateTimeField('date published')
189
190    class Choice(models.Model):
191        poll = models.ForeignKey(Poll)
192        choice = models.CharField(max_length=200)
193        votes = models.IntegerField()
194
195And activate the application by adding ``'sampleapp.polls'`` to
196``INSTALLED_APPS`` in ``src/sampleapp/sampleapp/settings.py``.  Also
197add ``'django.contrib.admin'`` to get the admin app in place.  Run
198``manage.py syncdb`` to get the tables in place.
199
200You can try ``silver serve .`` and go to ``/admin/`` to login and
201see your tables.  You might notice all the CSS is broken.
202
203Silver Lining serves static files out of the ``static/`` directory.
204You don't actually put ``static`` in the URLs, these files are
205available at the top-level (unless you create a ``static/static/``
206directory).  The best way to put files in there is generally symbolic
207links.
208
209For Django admin, do this::
210
211    $ cd static
212    $ ln -s ../lib/python/django/contrib/admin/media admin-media
213
214Now edit ``src/sampleapp/sampleapp/settings.py`` and change
215``ADMIN_MEDIA_PREFIX`` to ``'/admin-media'``.
216
217FIXME: probably some other links should be added.
218
219One *last* little thing you might want to do; replace this line in
220settings::
221
222    SECRET_KEY = 'ASF#@$@#JFAS#@'
223
224With this::
225
226    from silversupport.secret import get_secret
227    SECRET_KEY = get_secret()
228
229Then you don't have to worry about checking a secret into version
230control.
231
232Setting Up Your Deployed Database
233---------------------------------
234
235After you write an app and are ready to deploy it, you just run
236``silver update``.  *But*, while you'll get a blank database to
237use, it will be empty until you run ``syncdb``.  A good way to do that
238is::
239
240    $ silver run HOSTNAME src/myapp/manage.py syncdb
241
242You can use this for data imports or other management tasks as well.
243
244A more robust mechanism is to use the ``update_fetch`` setting in
245``app.ini``: this is a URL (provided *by* your application) that is
246fetched everytime your application is updated.  This URL can check the
247database, create tables, etc.  (In the future I expect this can use
248scripts in addition to URLs, at which point you can run ``syncdb``
249directly; for now you could also create a URL in your app that calls
250``syncdb`` programmatically.)