-
Notifications
You must be signed in to change notification settings - Fork 15
/
django-getting-started.html
137 lines (133 loc) · 18.6 KB
/
django-getting-started.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta name="generator" content="pandoc" />
<title>SLP: Django: Getting Started</title>
<style type="text/css">code{white-space: pre;}</style>
<link rel="stylesheet" href="../markdown.css" type="text/css" />
</head>
<body>
<h1 id="slp-django-getting-started">SLP: Django: Getting Started</h1>
<p><a href="index.html">Go up to the main SLP documents page</a> (<a href="index.md">md</a>)</p>
<h3 id="python-version">Python version</h3>
<p>On both the course server and the VirtualBox image, there are two versions of python installed. It is the system default version (<code>python -V</code>) that is used in the WSGI module (which is what runs the Django project in the web server). As of the writing of this tutorial, that is version 2.7.12. Running <code>python3 -V</code> indicates that Python 3.5.2 is also installed. These are the defaults for a stock version of Ubuntu 16.04 as of the writing of this document (August 2017).</p>
<h3 id="install-django">Install Django</h3>
<p>Django has already been installed on the VirtualBox image provided, the docker image provided, as well as on the course server.</p>
<p>To install Django on your own system, under Ubuntu 16.04, you need to install pip, the Python package manager: <code>sudo apt-get install python-pip</code>. If it is not installed, you will also want to install the <code>python-mysqldb</code> package so that Python can connect to the MySQL database. You can then install Django via <code>sudo pip install Django==1.11</code> (you may want to see if there is a newer release available than 1.11, which was the most recent release as of the writing of this document). Note that installing the python-django package under Ubuntu will NOT work, as that is a previous Django version.</p>
<h3 id="setting-up-a-new-django-project">Setting up a new Django project</h3>
<p>Much of these directions are based on the <a href="https://docs.djangoproject.com/en/1.11/intro/">Django intro tutorial</a> from <a href="https://www.djangoproject.com/">Django Project</a>. These directions are for Django version 1.11; if a newer version is released, then and you have to change the tutorial page version, via the link in the lower right, to 1.11, which is the version we are using.</p>
<p>To create a Django project, follow these steps. They are adapted from <a href="https://docs.djangoproject.com/en/1.11/intro/tutorial01/">part 1 of the Django tutorial</a>.</p>
<ol style="list-style-type: decimal">
<li>Enter <code>django-admin startproject mysite</code>. This will create a <code>mysite/</code> directory with a bunch of files in it.
<ul>
<li>For the <a href="hw-frameworks.html">Frameworks homework</a> (<a href="hw-frameworks.md">md</a>), you probably will want to use "djangohw" as the project name</li>
<li>You will need to change all instances of "mysite" in these directions to your actual project name ("djangohw", or whatever).</li>
<li>Note that you can call the binary <code>django-admin</code> or <code>django-admin.py</code>, as the former just invokes the latter.</li>
<li>The Django directory that is created should be in your home directory on the course server.</li>
</ul></li>
<li>To view your project, you can run <code>python manage.py runserver</code> from inside the <code>mysite/</code> directory. This will print a URL, such as <code>http://127.0.0.1:8000/</code> -- you can view that URL in your browser, and it should look exactly like the image at the very bottom of this page. This will only work locally, though -- you can't view a Django project shown via the "runserver" command from the course server very easily (at least, not without redirecting ports).</li>
<li>To update the database information, edit <code>mysite/mysite/settings.py</code>
<ul>
<li>To use MySQL, change the <code>ENGINE</code> value in <code>DATABASES</code> from <code>django.db.backends.sqlite3</code> to <code>django.db.backends.mysql</code></li>
<li>Enter values for your DB credentials: <code>USER</code>, <code>NAME</code>, <code>PASSWORD</code>, and <code>HOST</code>.</li>
<li><p>A completed <code>DATABASES</code> section might look like the following:</p>
<pre><code>DATABASES = {
'default': {
'ENGINE': 'django.db.backends.mysql',
'NAME': 'mst3k',
'USER': 'mst3k',
'PASSWORD': 'password',
'HOST': '127.0.0.1',
}
}</code></pre></li>
<li>Note that there is no easy way to add a DB table prefix to every table -- instead, you would have to specify the name of <em>every</em> table that Django uses. You can see a whole bunch of people getting all twitchy over this <a href="https://code.djangoproject.com/ticket/891">here</a>.</li>
<li>And edit <code>TIME_ZONE</code> to match our time zone. The particular value you want there is 'US/Eastern'.</li>
</ul></li>
<li>From the <code>mysite/</code> directory, run <code>python manage.py migrate</code>. This will set up the DB tables.
<ul>
<li>The 'superusers' that it prompts you for are a login for your web system -- you can use your userid, and pick any password that you'd like. Note that by setting the username and password here, you can skip the "Create an admin user" section at the top of <a href="https://docs.djangoproject.com/en/1.11/intro/tutorial02/">page 2 of the Django tutorial</a>.</li>
</ul></li>
</ol>
<p>At this point, you Django project is up and running, even if it doesn't do much. You can now start about half-way down on the <a href="https://docs.djangoproject.com/en/1.11/intro/tutorial01/#creating-models">Django tutorial, part 1</a> page (start at the "Creating models" section).</p>
<h3 id="viewing-it-locally">Viewing it locally</h3>
<p>As mentioned in <a href="https://docs.djangoproject.com/en/1.11/intro/tutorial01/">part 1 of the Django tutorial</a>, to view your Django project locally, you run <code>python manage.py runserver</code>, and then view it in the URL provided (likely <code>http://127.0.0.1:8000/</code>).</p>
<h3 id="registering-the-django-project-with-apache-on-the-course-server">Registering the Django project with Apache on the course server</h3>
<p>When running it locally, you view it via <code>python manage.py runserver</code>. But on the course server, you will have to configure it run through the apache web server. These directions are specifically for the course web server; the <a href="virtualbox-image-details.html">VirtualBox image</a> (<a href="virtualbox-image-details.md">md</a>) has <em>NOT</em> been configured to allow this to work (on the VirtualBox image, just use the "runserver" command).</p>
<p>When you have created your Django project, you will need to tell the web server that your file exists. The module that runs Python projects on the Apache web server is called WSGI (Web Server Gateway Interface), pronounced "wus-gee". On the server, there is a <code>wsgi-admin</code> command-line tool to do exactly that, since you can't edit the web server configuration files yourself. Note that you can only have one WSGI project registered at a time. You will need to find the wsgi.py file in your Django project (likely in <code>mysite/mysite/wsgi.py</code>, where <code>mysite</code> is the name of your Django project).</p>
<p>There are four main "modes" to that command:</p>
<ul>
<li><code>-register</code> will register a wsgi file, supplied with the <code>-file</code> flag</li>
<li><code>-list</code> will list your existing entry, including the ID (which is needed to remove that entry)</li>
<li><code>-remove</code> will remove a previously registered wsgi file via entry's ID number, which is specified via the <code>-id</code> flag</li>
<li><code>-regenerate</code> will regenerate the web server configuration files and reload the web server. This is automatically done on a <code>-register</code> or <code>-remove</code>. But it could be the case that somebody accidentally deleted their Django project files, which will cause the WSGI module to cause <strong>ALL</strong> of the WSGI projects to stop working -- the <code>-regenerate</code> command will re-create the configuration files without the missing Django projects.</li>
</ul>
<p>There are a few other flags to the above:</p>
<ul>
<li><code>-file <wsgi_file></code> specifies which file to register; it must be the <code>wsgi.py</code> file</li>
<li><code>-id <id_num></code> will remove the wsgi file entry with the specified <em>integer</em> ID; the IDs can be found via the <code>-list</code> flag</li>
<li><code>-compact</code> will cause the output of the <code>-list</code> to be one line per entry</li>
<li><code>-staticdir <dir></code> specifies what the static directory is; this must be a full path name (the default is a static/ sub-directory under the main project directory)</li>
</ul>
<p>Lastly, there are a few flags that are restricted as to who can use them (meaning only the root user can call these flags):</p>
<ul>
<li><code>-uid <uid_num></code> will register the wsgi file as a different user (you can find the UID of a user via <code>getent passwd <user></code>)</li>
<li><code>-nocheck</code> will skip the check as to whether the passed wsgi file is a valid wsgi file or not</li>
<li><code>-root</code> will register the file as http://server/user, rather than http://server/django/user</li>
<li><code>-all</code> will list all the registered wsgi files, including the ones that have been removed</li>
</ul>
<p>So, to register your file for the tutorial:</p>
<pre><code>wsgi-admin -register -file mysite/mysite/wsgi.py</code></pre>
<p>It doesn't matter what directory you run this command from, as long as you specify the correct wsgi.py file -- there is only one in the Django project directory that you have created. Once done, you should be able to view the project online at http://server/django/mst3k/, where "mst3k" is your userid. Note that this URL will give you a "Page not found (404)" error on a <em>YELLOW</em> background, which is because you have not set up your routing properly. This means that the web server is properly reading your Djagno project, but that your project is not yet properly configured (more on this below). If you get a "Not Found" error on a <em>WHITE</em> background, then either the URL is wrong, or you entered the wrong wsgi-admin command parameters. If you view http://server/django/mst3k/admin, it will present a Django administration login screen, and you can log in with the superuser information that you entered when you created the Django project (step 4 under "Setting up a new Django project", above).</p>
<p>To find the existing entries that you have:</p>
<pre><code>wsgi-admin -list</code></pre>
<p>Note that that command will also tell you the ID of your entry, which is a positive integer. Also note that you can only have one entry per account, so you will have to remove an existing entry if you want to create a new one (or if you want to change any of the settings).</p>
<p>To remove your entry, assuming it has an ID 42 (the ID is found via the <code>wsgi-admin -list</code> command):</p>
<pre><code>wsgi-admin -remove -id 42</code></pre>
<p>Once the system is registered properly, you can view the site at http://server/django/mst3k; you will get the following image. We'll get it working properly in the "Configuring the Django project" section, below.</p>
<div class="figure">
<img src="images/django-first-take.png" />
</div>
<h3 id="updating-the-django-project">Updating the Django project</h3>
<p>If you have updated your Django project -- meaning you have edited <em>any</em> of the files -- then you will need to tell the web server that this has occurred. While you can reload the web server (via the <code>reload-apache2</code> command), it's much better to update the timestamp on your wsgi.py file. To do this, use the <code>touch</code> command:</p>
<pre><code>touch ~/mysite/mysite/wsgi.py</code></pre>
<p>This will update the timestamp on the wsgi.py file to the current time. The web server (actually the WSGI module) will detect this, and reload the project.</p>
<p>If you are still running into problems (such as Internal Server Errors (500)), try reloading the web server via <code>reload-apache2</code>.</p>
<h3 id="sqlite-to-mysql">SQLite to MySQL</h3>
<p>If you used the docker image, then you likely kept the data for the app in a SQLite3 database. You can use the framework's command to create the tables. You can use the <a href="http://www.sqlitetutorial.net/sqlite-dump/">.dump command</a> to extract the data, and then enter it into the MySQL database on the course server. If you are unsure what the format of the database configuration file should be, create a new app (with a different name) that uses MySQL, and look at the file therein for the format (or just copy the database configuration file over).</p>
<p>It may be that the SQLite dump does not work well under MySQL. One option is to edit the dump extensively, but that is long and annoying to do. Another option is to migrate the DB through the framework on the course server, and re-enter the data into the DB (from the tutorial, copy and paste all the insert commands).</p>
<h2 id="configuring-the-django-project">Configuring the Django project</h2>
<p>While the project works, many things will still need tweaking.</p>
<h5 id="setting-the-static-directory">Setting the static directory</h5>
<p>If you look at http://server/django/mst3k/admin (notice the "/admin" at the end), it will look like the following:</p>
<div class="figure">
<img src="images/django-static-bad.png" />
</div>
<p>You will note that there is no formatting, as the various files needed for that formatting (images, CSS files, etc.) can not be found. These files are called <em>static files</em>, as their content does not change (much).</p>
<p>There are many static files that are needed for a Django project; these are described in more detail in <a href="https://docs.djangoproject.com/en/1.11/intro/tutorial06/">part 6 of the Djago tutorial</a>. Normally, the static files are found in http://server/static. However, as there are many Django projects running on this web server, there are many <em>different</em> static directories, and thus the URL is different: ours will be at http://server/django/mst3k/static.</p>
<p>This tutorial assumes that your static files are going to be kept in a <code>static/</code> sub-directory of your project directory (i.e., the <code>static/</code> directory is in the same directory as the <code>manage.py</code> file). You do not need to make that directory yet; that will be done below. The wsgi-admin program, which you used above, makes that assumption (where your static directory is) as well. If you want your static directory in a different location, then you will need to re-run the wsgi-admin program (after removing your current entry) and use the <code>-staticdir</code> flag, which is described above.</p>
<p>You need to tell the Django project where these files are. In the settings.py file (which you edited above), you will need to add the following two lines. The first, <code>STATIC_URL</code>, is the URL where the static files are found; the second, <code>STATIC_ROOT</code>, is the <em>filesystem</em> path where the files are found.</p>
<pre><code>STATIC_URL = '/django/mst3k/static/'
STATIC_ROOT = '/home/slp/mst3k/mysite/static/'</code></pre>
<p>Lastly, you need to put all the necessary static files into the correct directory (again, presumably /home/slp/mst3k/mysite/static/). To do this, run (from the main project directory):</p>
<pre><code>python manage.py collectstatic</code></pre>
<p>You will have to confirm that it intends to overwrite files. This command also creates the /home/slp/mst3k/mysite/static/ directory.</p>
<p>Lastly, reload the project (<code>touch mysite/wsgi.py</code>), and view the admin page again (http://server/django/mst3k/admin); it should look <em>exactly</em> like the following, other than the userid (if it does not, then something went wrong):</p>
<div class="figure">
<img src="images/django-static-good.png" />
</div>
<p>Once that is done, the tutorial (specifically, <a href="https://docs.djangoproject.com/en/1.11/intro/tutorial06/">part 6</a>) proceeds normally, and no changes to the tutorial are needed.</p>
<h5 id="configuring-the-django-projects-urls">Configuring the Django project's URLs</h5>
<p>This section assumes that there is a <code>polls</code> app in the project, which is what is done in the tutorial that is part of the <a href="hw-frameworks.html">Frameworks homework</a> (<a href="hw-frameworks.md">md</a>). If you made a different named app, just replace "polls" with the app name in the instructions below. This section also assumes you have a default view (we'll use <code>index</code>) for that app. This is done in the first half of <a href="https://docs.djangoproject.com/en/1.11/intro/tutorial03/">page 3 of the Django tutorial</a>. If you have not yet added that app <em>and</em> that view to the project, then this won't work -- come back to this spot in the instructions when you have added that app (and view).</p>
<p>Currently, http://server/django/mst3k gives a page not found error, but http://server/django/mst3k/polls works; we are going to redirect the former to the latter. The first half of <a href="https://docs.djangoproject.com/en/1.11/intro/tutorial03/">page 3 of the Django tutorial</a> had you create a polls/urls.py to add the index view. In addition, it had you edit mysite/urls.py to add a "polls" line -- this told Django how to route one to the polls app. What we are going to do is to tell Django that if you view the <em>entire</em> project (at http://server/django/mst3k) to <em>also</em> route one to the polls app.</p>
<p>To do this, add a the following line to the following into that urlpatterns array (above the existing 'polls' line):</p>
<pre><code> url(r'^', include('polls.urls', namespace="polls")),</code></pre>
<p>This will cause the base URL of the Djagno project (http://server/django/mst3k) to display the contents of the polls app.</p>
<h3 id="initial-djano-project-image-but-only-via-the-runserver-command">Initial Djano project image (but only via the "runserver" command!)</h3>
<p>If you are running this on the course server, then you will <em>NOT</em> see this page. Instead, verify that you can see the http://server/django/mst3k/admin, which should look like the images above.</p>
<div class="figure">
<img src="images/django-initial.png" />
</div>
</body>
</html>