« back to all changes in this revision
Viewing changes to README.rst
- browse files at revision 26
- compare with another revision
- download diff
- download tarball
- view history from revision 26
- Committer: Jorge O. Castro
- Date: 2013-08-01 20:30:04 UTC
- Revision ID: jorge@ubuntu.com-20130801203004-84orz28gen9ggz8n
Converting this to Markdown so the GUI renders it.
- files removed:
- README.rst
added
removed
README.rst
1
Juju charm python-django
2
========================
3
4
:Author: Patrick Hetu <patrick.hetu@gmail.com> and Bruno Girin
5
6
What is Django?
7
...............
8
9
Django is a high-level web application framework that loosely follows
10
the model-view-controller design pattern. Python's equivalent to Ruby
11
on Rails, Django lets you build complex data-driven websites quickly
12
and easily - Django focuses on automating as much as possible and
13
adhering to the "Don't Repeat Yourself" (DRY) principle. Django
14
additionally emphasizes reusability and "pluggability" of components;
15
many generic third-party "applications" are available to enhance
16
projects or to simply to reduce development time even further.
17
18
Notable features include:
19
20
* An object-relational mapper (ORM)
21
* Automatic admin interface
22
* Elegant URL dispatcher
23
* Form serialization and validation system
24
* Templating system
25
* Lightweight, standalone web server for development and testing
26
* Internationalization support
27
* Testing framework and client
28
29
The charm
30
---------
31
32
This charm will install Django. It can also install your Django
33
project and his dependencies from either a template or from a
34
version control system.
35
36
It can also link your project to a database and sync the schemas.
37
This charm also come with a Fabric fabfile to interact with the
38
deployement in a cloud aware manner.
39
40
41
Quick start
42
-----------
43
44
Simply::
45
46
juju bootstrap
47
juju deploy python-django
48
49
juju deploy postgresql
50
juju add-relation python-django postgresql:db
51
52
juju deploy gunicorn
53
juju add-relation python-django gunicorn
54
juju expose python-django
55
56
In a couple of minute, your new (vanilla) Django site should be ready at
57
the public address of gunicorn. You can find it in the output of the
58
`juju status` command.
59
60
This is roughtly equivalent to the `Creating a project`_ step in Django's
61
tutorial.
62
63
.. _`Creating a project`: https://docs.djangoproject.com/en/1.5/intro/tutorial01/#creating-a-project
64
65
Example: Deploying using site a template
66
----------------------------------------
67
68
Setup your Django specific parameters in mydjangosite.yaml like this one::
69
70
mydjangosite:
71
project_template_url: https://github.com/xenith/django-base-template/zipball/master
72
project_template_extension: py,md,rst
73
74
Note:
75
76
If your using juju-core you must remove the first line
77
of the file and the indentation for the rest of the file.
78
79
2. Deployment with `Gunicorn`::
80
81
juju bootstrap
82
juju deploy --config mydjangosite.yaml mydjangosite
83
84
juju deploy postgresql
85
juju add-relation mydjangosite postgresql:db
86
87
juju deploy gunicorn
88
juju add-relation mydjangosite gunicorn
89
juju expose mydjangosite
90
91
92
Example: Deploying using code repository
93
----------------------------------------
94
95
1. Setup your Django specific parameters in mydjangosite.yaml like this one::
96
97
mydjangosite:
98
vcs: bzr
99
repos_url: lp:~patrick-hetu/my_site
100
101
Note:
102
103
If your using juju-core you must remove the first line
104
of the file and the indentation for the rest of the file.
105
106
2. Deployment with `Gunicorn`::
107
108
juju bootstrap
109
juju deploy --config mydjangosite.yaml python-django
110
111
juju deploy postgresql
112
juju add-relation python-django postgresql:db
113
114
juju deploy gunicorn
115
juju add-relation python-django gunicorn
116
juju expose python-django
117
118
Note:
119
120
If your using juju-core you must add --upload-tools to the
121
`juju bootstrap` command.
122
123
3. Accessing your new Django site should be ready at the public address of
124
Gunicorn. To find it look for it in the output of the `juju status` command.
125
126
127
Project layout and code injection
128
---------------------------------
129
130
Taking the previous example, your web site should be on the Django node at::
131
132
/srv/python-django/
133
134
As you can see there the charm have inject some code at the end of your settings.py
135
file (or created it if it was not there) to be able to import what's in the
136
`juju_settings/` directory.
137
138
It's recommended to make your vcs to ignore database and secret files or
139
any files that have information that you don't want to be publish.
140
141
142
Upgrade the charm
143
-----------------
144
145
This charm allow you to upgrade your deployment using the Juju's
146
`upgrade-charm` command. This command will:
147
148
* upgrade Django
149
* upgrade additionnal pip packages
150
* upgrade additionnal Debian packages
151
* upgrade using requirements files in your project
152
153
Management with Fabric
154
----------------------
155
156
Fabric_ is a Python (2.5 or higher) library and command-line tool for
157
streamlining the use of SSH for application deployment or systems
158
administration tasks.
159
160
It provides a basic suite of operations for executing
161
local or remote shell commands (normally or via sudo) and uploading/downloading
162
files, as well as auxiliary functionality such as prompting the running user
163
for input, or aborting execution.
164
165
.. _Fabric: http://docs.fabfile.org
166
167
This charm includes a Fabric script that use Juju's information to perform various
168
tasks.
169
170
For a list of tasks type this command after bootstraping your Juju environment::
171
172
fab -l
173
174
For example, with a python-django service deployed you can run commands on all its units::
175
176
fab -R python-django pull
177
[10.0.0.2] Executing task 'pull'
178
[10.0.0.2] run: bzr pull lp:~my_name/django_code/my_site
179
...
180
[10.0.0.2] run: invoke-rc.d gunicorn restart
181
...
182
183
Or you can also run commands on a single unit::
184
185
fab -R python-django/0 manage:createsuperuser
186
...
187
[10.0.0.2] out: Username (leave blank to use 'ubuntu'):
188
189
190
Limitation:
191
192
* You can only execute task for one role at the time.
193
But it can be a service or unit.
194
195
If you want to extend the fabfile check out fabtools_ .
196
197
.. _fabtools: http://fabtools.readthedocs.org/
198
199
Security
200
--------
201
202
Note that if your using a *requirement.txt* file the packages will
203
be downloaded with *pip* and it doesn't do any cryptographic
204
verification of its downloads.
205
206
Writing application charm
207
-------------------------
208
209
To create an application subordinate charm that can be related to this charm you need
210
at least to define an interface named `directory-path` in your `metadate.yaml` file
211
like this::
212
213
[...]
214
requires:
215
python-django:
216
interface: directory-path
217
scope: container
218
optional: true
219
220
When you will add a relation between your charm and the python-django charm
221
the hook you will be able to get those relation variables:
222
223
* settings_dir_path
224
* urls_dir_path
225
* django_admin_cmd
226
* install_root
227
228
now your charm will be informed about where it need to add new settings
229
and urls files and how to run additionnal Django commands.
230
The Django charm reload Gunicorn after the relation to catch the changes.
231
232
Changelog
233
---------
234
235
3:
236
237
Notable changes:
238
239
* Rewrite the charm using python instead of BASH scripts
240
* Django projects now need no modification to work with the charm
241
* Use the `django-admin startproject` command with configurable arguments if no repos is specified
242
* Juju's generated settings and urls files are now added in a juju_settings
243
and a juju_urls directories by default
244
* New MongoDB relation (server side is yet to be done)
245
* New upgrade hook that upgrade pip and debian packages
246
* Expose ports is now handle by the charm
247
248
Configuration changes:
249
250
* default user and group is now ubuntu
251
* new install_root option
252
* new django_version option
253
* new additional_pip_packages option
254
* new repos_branch,repos_username,repos_password options
255
* new project_name, project_template_extension, project_template_url options
256
* new urls_dir_name and settings_dir_name options
257
* new project_template_url and project_template_extension options
258
* database, uploads, static, secret and cache settings locations are now configurable
259
* extra_deb_pkg was renamed additional_distro_packages
260
* requirements was renamed requirements_pip_files and now support multiple files
261
* if python_path is empty set as install_root
262
263
Backwards incompatible changes:
264
265
* swift support was moved to a subordinate charm
266
* postgresql relation hook was rename pgsql instead of db
267
268
2:
269
270
Notable changes:
271
272
* You can configure all wsgi (Gunicorn) settings via the config.yaml file
273
* Juju compatible Fabric fabfile.py is included for PAAS commands
274
* Swift storage backend is now optional
275
276
Backwards incompatible changes:
277
278
* Use splited settings and urls
279
* Permissons are now based on WSGI's user and group instead of just being www-data
280
* media and static files are now in new directories ./uploads and ./static/
281
* Deprecated configuration variables: site_domain, site_username, site_password, site_admin_email
282
283
284
1:
285
286
Initial release
287
288
Inspiration
289
-----------
290
291
* http://www.deploydjango.com
292
* http://lincolnloop.com/django-best-practices/
293
* https://github.com/30loops/djangocms-on-30loops.git
294
* https://github.com/openshift/django-example
295
* http://lincolnloop.com/blog/2013/feb/15/django-settings-parity-youre-doing-it-wrong/
296
* http://tech.yipit.com/2011/11/02/django-settings-what-to-do-about-settings-py/
297
* http://www.rdegges.com/the-perfect-django-settings-file/
298
* https://github.com/xenith/django-base-template.git
299
* https://github.com/transifex/transifex/blob/devel/transifex/settings.py
300
* http://peterlyons.com/problog/2010/02/environment-variables-considered-harmful
Loggerhead is a web-based interface for Breezy
Version: 2.0.1