Potlatch 2/Deploying Potlatch 2

From OpenStreetMap Wiki
Jump to: navigation, search
Customised version of P2 for sustainable mapping

Potlatch 2 can be deployed on your own website, so you can create an editor targeted to your users - whether they have a particular interest (e.g. cycling), or come from a particular country, or whatever. You don't need to write any code or compile Potlatch 2 to do this; you just need a little experience in configuring websites.

Getting the files

Pull down all the files from http://random.dev.openstreetmap.org/potlatch2/ , including the full contents of the features/, icons/ and fills/ directories. (You don't need halcyon.html, server.rb or tinyamf.cgi.) These are the resource files that Potlatch 2 needs. (You'll need to keep them in the same directories.)

potlatch2.swf is the actual app itself, and is automatically compiled and updated when the P2 code is changed. Potlatch 2 is under rapid development - please make sure you update your copy regularly!

Upload them to a directory on your webserver. (potlatch2.swf should be in the same directory as the other files.)

Setting up Potlatch 2

You'll need to edit the various settings in potlatch2.html as appropriate.

To specify the location to start editing, edit this:

lat=51.875
lon=-1.492

To specify the location of the OpenStreetMap server, edit these. To talk to the main OSM server, you'll want to replace "api06.dev" with "www". If you want Potlatch 2 to work with your own server, you need to change all of these URLs to match that of your server.

args["api"] = "http://api06.dev.openstreetmap.org/api/0.6/";
args["policy"] = "http://api06.dev.openstreetmap.org/api/crossdomain.xml";
args["oauth_policy"] = "http://api06.dev.openstreetmap.org/oauth/crossdomain.xml";
args["oauth_request_url"] = "http://api06.dev.openstreetmap.org/oauth/request_token";
args["oauth_access_url"] = "http://api06.dev.openstreetmap.org/oauth/access_token";
args["oauth_auth_url"] = "http://api06.dev.openstreetmap.org/oauth/authorize";
args["serverName"] = "api06 Test On Dev";

To specify the localization and set the Potlatch 2 in your language:

args["locale"] =  "fr_FR";  /*available languages (on 05/05/2011): de_DE en_GB, en_US, pl_PL*/

Keep this line as it is:

args["connection"] = "XML";

Finally, you need to tell the OSM server about your instance of Potlatch 2. Go to your OSM user page and click 'oauth settings', then 'Register your application'. Note that you must register the application for every server you use. To be able to test on api06.dev.openstreetmap.org, you must also register on that server.

When prompted, enter the name of your instance (e.g. "Ruritanian Potlatch 2") and its URL (e.g. "http://openstreetmap.rt/potlatch2"). Under 'Callback URL', you can optionally enter the URL of a page to say "Thanks, now close this OSM window and go back to Potlatch" when your users have authenticated their account. Under 'Support URL', you can optionally enter a help URL.

Then tick, at the least, 'modify the map', and click 'Register'. You will be given an OAuth 'consumer key' and 'consumer secret'. Copy and paste them into the relevant lines in potlatch2.html:

args["oauth_consumer_key"] = "fiM1IoqnKJk4JCfcl63DA";
args["oauth_consumer_secret"] = "7fYgJK9M4vB1CvBZ6jEsPGxYK9UD1hEnI6NqTxNGs";

Your Potlatch 2 instance is now ready to go!

Optional parameters

In addition to the parameters given above, there are a few more optional parameters:

args["show_help"] = "once"; //shows the help dialog on first startup. Set to "always" to force the dialog to show every time. Defaults to not showing the dialog on startup
args["site_name"] = "OpenStreetMap";// customises the help dialog slightly (e.g. "through this website" becomes "through the Ruritania website")
args["force_auth"] = "force";
args["gpx_url"]= "http://www.whereyourgpxis.com/something.gpx";

Setting up a custom server

If your version of Potlatch 2 is talking to the main OpenStreetMap database, you don't need to do anything more.

If it is talking to your own database, running on the same domain, you don't need to do anything more either.

However, if it is talking to your own database running on a different domain, that domain (the one with the database on it) will need a crossdomain.xml file at root level to say "let Flash access the data from here". The standard OSM Rails code includes a permissive set of crossdomain.xml files (e.g. http://git.openstreetmap.org/rails.git/blob/HEAD:/public/crossdomain.xml and http://git.openstreetmap.org/rails.git/blob/HEAD:/public/api/crossdomain.xml). If you're using different code entirely, simply pull down the permissive file from http://api.flickr.com/crossdomain.xml and save it at root level.

Your Flash player may expect it to be delivered in a specific MIME type. Adobe discusses the Flash policy file, but in short, for Apache httpd, the following lines in its config should work:

<Files crossdomain.xml>
  ForceType text/x-cross-domain-policy
</Files>

Customising Potlatch 2

Potlatch 2's presets and styles can be fully customised.

Presets are defined in map_features.xml. See the file description for details.

Stylesheets are defined in MapCSS files which are indexed in stylesheets.xml.

Background image layers (in '900913' Spherical Mercator format) are indexed in imagery.xml. If you have a WMS layer, you can use Whoots to transform it into 900913 tiles for use in Potlatch. Note that Potlatch 2 uses $z, $x and $y references in the WMS URL, not the !/!/! scheme used by Potlatch 1.

Grouping images into .zip files

To avoid loading hundreds of individual images each time, you can tell Potlatch 2 that it should look in .zip archives (which will be preloaded) for certain filepaths.

Add something like this to your embedding page:

args["assets"] = "assets/icons.zip=icons/;assets/features_pois.zip=features/pois/"; 

That tells Potlatch 2 to look in "assets/icons.zip" for any file with a path starting "icons/", and so on. So if your stylesheet references "icons/motorway.png", P2 will look for motorway.png in assets/icons.zip. If it references "features/pois/pub.png", P2 will look for pub.png in assets/features_poi.zip. You get the idea.

Customised versions already up and running