source: subversion/sites/other/tilesAtHome_tahngo/docs/INSTALL @ 9468

Last change on this file since 9468 was 9285, checked in by spaetz, 12 years ago

improved INSTALL instructions.

File size: 5.5 KB
Line 
1PREREQUISITES
2-------------
3
4The Tahngo server, as currently tested, requires the following software:
5
6- Python.  (2.4 works)
7- Django.  (0.96 works)
8- Apache.  (2.2 works)
9- mod_python.  (3.3 works)
10
11Django needs a database module to store its data in.  If you don't have a preference, sqlite is the simplest to use.  You will need a python module for your database, such as python-mysql or python-sqlite (python-sqlite2 2.3.3 works).
12
13If you get Django errors that max_length is invalid, try a newer version from Django svn. (Should be fixed by not using max_length now)
14
15INSTALLATION
16------------
17- Download the main directory from the OpenStreetMap svn server.  Put it in a location of your choice, eg. /usr/local/share/tah.  The base directory name must be "tah".  The svn download will give you a directory named "tileAtHome_tahngo" by default; change it to "tah".
18- The "Tiles" directory should be moved to the place where you want to store all the tileset files. The setting "base_tile_path" should point to this directory as it will save tileset files here and expect the stock images (blank sea/land/error) here.
19- The "media" directory contains files that should be accessible through the web server and should be moved to a place where the files can be served through apache. I think the setting MEDIA_URL in tah.settings needs to point to one directory below "media".
20- Move settings.py.example to settings.py and adapt the settings in tah.settings to your configuration (database choice, url handler, etc)
21- Run "python manage.py syncdb" to create the database
22- Configure your web server for the new paths.  See "Apache Configuration" below.
23- In a web browser, go to the /admin interface and add the settings "base_tile_path", "unzipPath","logFile" to the table Settings.
24  In the case of tah.osm.org these settings are "/mnt/agami/openstreetmap/tah/Tiles", "/tmp", and "tah.log" respectively.
25- in tah_intern/Tile.py the base_tile_path is hardcoded for efficiency reasons. Open that file and adapt the path there too.
26- tah_intern/views.py currently contains a hardcoded path to the log file location. Adapt the line:   f = open('/home/spaetz/tah/tah_intern/tah.log', 'rU')
27- tah_intern/LegacyTileset.py contains hardcoded paths to your oceantiles.dat file and your fallback legacy tile directories.
28
29- Configure the html templates for the URL to your tile server.  In the templates directory, the files base_browse.html, base_browse_slippy.html, and tile_details.html refer to tah.openstreetmap.org/Tile.  For a test installation, change this to the URL for your "/Tile" location in your Apache configuration below.
30
31APACHE CONFIGURATION
32--------------------
33The following snippet was sufficient in the apache vhost configuration to make it work. If the main apache config cannot be modified it worked to have the stuff in a .htaccess file in the corresponding directories too.
34
35        <Location />
36                SetHandler python-program
37                PythonHandler django.core.handlers.modpython
38                SetEnv DJANGO_SETTINGS_MODULE tah.settings
39                #adapt next line to whatever your install base directory is
40                PythonPath "['/usr/local/share/'] + sys.path"
41                #PythonAutoReload Off
42                PythonDebug Off
43        </Location>
44        <Location /media>
45                SetHandler None
46        </Location>
47        <Location /Tiles>
48                SetHandler python-program
49                #adapt next line to whatever your install base directory is
50                PythonPath "['/usr/local/share/'] + sys.path"
51                PythonHandler  tah.tah_intern.serve_tiles
52                #PythonAutoReload Off
53                PythonDebug Off
54        </Location>
55
56You can also put these in a subdirectory of your web server by changing the path in the Location lines.
57
58(Note: Currently, the actual tile serving only works through Apache mod_python.  Much of the other parts of the server (admin and browse screens) can be run in a Django standalone server using "python manage.py runserver" for testing purposes.)
59
60USAGE
61-----
62t@h clients can connect to the server without explicitely creating an account. If clients are configured with their
63OpenStreetMap account email (display user name will not work for account creation, but should work as username afterwards, although there is no reason to prefer that to the email) and regular OSM password, the account will be automatically created.
64Passwords are cached in a hashed form on the t@h server, so subsequent OpenStreetMap Email or Password changes will not be automatically propagate to the t@h server. In case of a wrong password, the server tries to refetch the password from OpenStreetMap, so password changes (should theoretically) be possible.
65
66In the web admin interface, you will need to add some "layers" for your maps. In t@h these are currently: tile (the default layer from z0-17), captionless (from z0-17; part of the default layers), maplint(transparent; from z12-17; part of the default layers), and caption (transparent; from z0-17).
67
68Processing uploaded tilesets will not happen automatically by the django server this is done in a separate thread. In the directory tah_intern, you need to call "./process_uploads" to unzip the uploads and put the resulting tilesetfiles to their final location. To start and stop this process more conveniently there is Tools/startstop_process_uploads which is a variant of a Debian like /etc/init.d/ script. You need to adapt some paths in here (and create the directory where the .pid file will be saved) and you can then use ./startstop_process_ploads start|stop|restart to start the tile processing. If it already runs, it will not be started again, so I run the startstop script with option "start" every half hour in a cron script to restart it after a reboot (or an unlikely crash).
Note: See TracBrowser for help on using the repository browser.