| 34 | | Answer "n" to this question unless you really know what you're doing. |
| 35 | | It's mainly there for developers. (If you already have a configuration |
| 36 | | file, and wish to use it without the build script asking you this |
| 37 | | question, run Build.PL with the option --force. This will also skip |
| 38 | | the "Continue with install?" question.) |
| 39 | | |
| 40 | | |
| 41 | | "What type of database do you want the site to run on?" |
| 42 | | |
| 43 | | Answer "postgres", "mysql", or "sqlite". |
| 44 | | |
| 45 | | |
| 46 | | "What's the name of the database that this site runs on?" |
| 47 | | "...the database user that can access that database?" |
| 48 | | "...the password that they use to access the database?" |
| 49 | | |
| 50 | | You should create (or ask your ISP/sysadmin to create) a database |
| 51 | | specifically for the use of OpenGuides. If you have more than one |
| 52 | | OpenGuides installation, for example if you run guides for more than |
| 53 | | one city, each installation will need its own database. |
| 54 | | |
| 55 | | |
| 56 | | "...the machine that the database is hosted on? (blank if local" |
| 57 | | |
| 58 | | If the database is running on a local machine with username/password |
| 59 | | authentication then just press RETURN to skip this question. If it |
| 60 | | is running on a local machine with IDENT authentication then you may |
| 61 | | need to answer "localhost" to this question. If it is running on a |
| 62 | | remote machine then enter the full hostname of that machine. |
| 63 | | |
| 64 | | |
| 65 | | "What do you want the script to be called?" |
| 66 | | |
| 67 | | The default is for the main script to be called "wiki.cgi", but |
| 68 | | you may prefer to name it after your city - "leeds-guide.cgi" for |
| 69 | | example. Note that your webserver may be configured to only allow |
| 70 | | execution of scripts ending in, for example, ".cgi" |
| 71 | | |
| 72 | | |
| 73 | | "What directory should I install it in?" |
| 74 | | |
| 75 | | You need to pick a directory for the OpenGuides software to be |
| 76 | | installed in. This must be one known to the webserver as containing |
| 77 | | CGI scripts. You will need to have write permission on this directory |
| 78 | | when you come to run "perl Build install"; unless this is a private |
| 79 | | directory belonging to you then this might require an 'su' or 'sudo' |
| 80 | | to root under Unix. |
| 81 | | |
| 82 | | |
| 83 | | "What directory should I install the templates in?" |
| 84 | | "Where should I look for custom templates?" |
| 85 | | |
| 86 | | Normally these will be in the install directory, but they can be anywhere. |
| 87 | | Custom templates are intended to be user-modified, so you might want to |
| 88 | | put them somewhere in /etc. |
| 89 | | |
| 90 | | |
| 91 | | "What URL does the install directory map to?" |
| 92 | | |
| 93 | | Give the full address needed to access the installation directory with |
| 94 | | a web browser - for example http://london.openguides.org/ |
| 95 | | |
| 96 | | |
| 97 | | "Do you want me to munge a custom lib path into the scripts?" |
| 98 | | |
| 99 | | If you have installed some or all of the required Perl modules (or indeed |
| 100 | | the OpenGuides modules themselves) into a private directory, you will |
| 101 | | need to tell the scripts where to find these modules. Enter the paths |
| 102 | | to search here just as you would enter them in a 'use lib qw( ... );' |
| 103 | | in a Perl script. |
| 104 | | |
| 105 | | |
| 106 | | "Do you want to use Plucene for searching?" |
| 107 | | |
| 108 | | This question is no longer asked, but documentation here is retained for |
| 109 | | the benefit of people upgrading. |
| 110 | | |
| 111 | | If you are changing to Plucene from Search::InvertedIndex, you will |
| 112 | | need to do two things: |
| 113 | | - either delete your old indexes (they're just files in the index |
| 114 | | directory) or use a different index directory |
| 115 | | - reindex your entire wiki (see reindex.pl in the examples/ |
| 116 | | directory of this distribution) |
| 117 | | |
| 118 | | |
| 119 | | "What directory can I use to store indexes in for searching?" |
| 120 | | |
| 121 | | You need a directory to store files used as indexes for the site. The |
| 122 | | user that your script will run as will need write permission on this |
| 123 | | directory. Under some webserver configurations this might be a |
| 124 | | dedicated user - 'nobody' or 'www-data' for example, but for many |
| 125 | | multi-user systems this will just be yourself. |
| 126 | | |
| 127 | | |
| 128 | | "Do you want to enable page deletion?" |
| 129 | | "Please specify a password for the site admin." |
| 130 | | |
| 131 | | The default is to disable page deletion. If you choose to enable the |
| 132 | | page deletion mechanism then you will need to add a password to your |
| 133 | | wiki.conf by answering the question above or manually using a line such as |
| 134 | | admin_pass = putyourpasswordhere |
| 135 | | Users who know this password will be able to delete unwanted pages - |
| 136 | | along with all their history - from your wiki. |
| 137 | | *** USE WITH CAUTION. DELETED PAGES CANNOT BE RECOVERED. *** |
| 138 | | |
| 139 | | |
| 140 | | "What's the URL of the site's stylesheet?" |
| 141 | | |
| 142 | | Supplying an answer to this question is optional. There are example |
| 143 | | stylesheets in the examples/ directory - note that these will not be |
| 144 | | automatically installed. |
| 145 | | |
| 146 | | |
| 147 | | "What's the wiki called?" |
| 148 | | |
| 149 | | This is a title which will appear at the top of every page. If you have |
| 150 | | more than one OpenGuides installation at the same site then each should |
| 151 | | have a unique name, since this name is used to manage user preferences. |
| 152 | | |
| 153 | | |
| 154 | | "Do you want the navigation bar included on the home page?" |
| 155 | | |
| 156 | | Answer "y" or "n". |
| 157 | | |
| 158 | | |
| 159 | | "Do you want the ten most recent changes included on the home page?" |
| 160 | | |
| 161 | | Answer "y" or "n". |
| 162 | | |
| 163 | | |
| 164 | | "Do you want the Random Page link to avoid returning a locale page? |
| 165 | | "Do you want the Random Page link to avoid returning a category page? |
| 166 | | |
| 167 | | Answer "y" or "n". The defaults are "n", which means that Random Page is as |
| 168 | | likely to return a category or locale page as anything else. If the category |
| 169 | | and locale pages on your Guide are generally just lists of things in that |
| 170 | | category/locale, you probably want to pick "y" here. If, on the other hand, |
| 171 | | your category/locale pages generally have substantial content of their own, |
| 172 | | you may prefer to choose "n". |
| 173 | | |
| 174 | | |
| 175 | | "Do you want the content to appear above the navbar in the HTML?" |
| 176 | | |
| 177 | | Answer "y" or "n". The default is "n", for reasons of backwards |
| 178 | | compatibility with existing stylesheets, but the recommended answer is |
| 179 | | "y", as this will help search engines to find the most relevant parts |
| 180 | | of your pages. |
| 181 | | |
| 182 | | |
| 183 | | "What should the home page of the wiki be called?" |
| 184 | | "How would you describe the wiki?" |
| 185 | | |
| 186 | | Self-explanatory. |
| 187 | | |
| 188 | | |
| 189 | | "What city is the wiki based in?" |
| 190 | | "What country is the wiki based in?" |
| 191 | | |
| 192 | | If the wiki will not be city or country specific you can leave either or |
| 193 | | both of these blank. |
| 194 | | |
| 195 | | |
| 196 | | "Contact email address for the wiki admin?" |
| 197 | | |
| 198 | | Self explanatory. |
| 199 | | |
| 200 | | |
| 201 | | "What language will the site be in? (Please give an ISO language code.)" |
| 202 | | |
| 203 | | eg "en" for English, "it" for Italian. |
| 204 | | See http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt |
| 205 | | |
| 206 | | |
| 207 | | "What's the name of the node or page to use for the text formatting |
| 208 | | rules link?" |
| 209 | | "What URL do you want to use for the text formatting rules" |
| 210 | | |
| 211 | | From 0.19, OpenGuides allows users to choose whether or not to have a |
| 212 | | permanent link to the text formatting rules node or page in their navbar. |
| 213 | | You need to put the name of that node or URL in here for it to work, though. |
| 214 | | You might want to call the node "Text Formatting Examples", |
| 215 | | "Text Formatting Rules", "House Style" or whatever. |
| 216 | | |
| 217 | | Note that these the latter question will override the former, so if you |
| 218 | | want to use a local node make sure to leave the latter blank. |
| 219 | | |
| 220 | | "Make node titles link to node backlinks (C2 style)?" |
| 221 | | |
| 222 | | This refers to turning titles into links which bring up a list of referring |
| 223 | | pages. This was the convention with older wikis ("C2" refers to the original |
| 224 | | wiki at http://c2.com/cgi/wiki), but is not intuitive. |
| 225 | | |
| 226 | | "Do you have a Google Maps API key to use with this guide?" |
| 227 | | |
| 228 | | If you want Google Maps integration, you need to register with Google to get |
| 229 | | an API key. Visit http://www.google.com/apis/maps/signup.html and follow the |
| 230 | | instructions. Paste the great long string into the console window where you |
| 231 | | are installing. See README.GMAPS for more information. |
| 232 | | |
| 233 | | "What is the longitude of the centre point of a map to draw for your guide?" |
| 234 | | "What is the latitude of the centre point of a map to draw for your guide?" |
| 235 | | |
| 236 | | It's probably a good idea to pick some notionally central point for your |
| 237 | | guide. For example, Carfax for Oxford, Charing Cross for London. As a |
| 238 | | convenience, you may paste in a Google Maps URL for the centre longitude |
| 239 | | question and the (long,lat) will be parsed out from the URL. |
| 240 | | |
| 241 | | "What default zoom level shall we use for Google Maps?" |
| 242 | | "What default zoom level shall we use for Google Maps in the search results?" |
| 243 | | |
| 244 | | The defaults are probably appropriate in most cases. |
| 245 | | |
| 246 | | "Would you like to display a Google Map on every node that has geodata?" |
| 247 | | |
| 248 | | Answer "y" or "n". Note that an answer of "y" will only take effect if you've |
| 249 | | supplied a Google Maps API key above. Note further that users can choose to |
| 250 | | turn this off in their preferences. |
| 251 | | |
| 252 | | "Forcibly treat stored lat/long data as if they used the WGS84 ellipsoid?" |
| 253 | | |
| 254 | | Default this answer if you don't know what it means. |
| 255 | | |
| 256 | | "Do you have a Google Analytics key to use with this guide?" |
| 257 | | |
| 258 | | If you'd like to use Google Analytics to track the traffic on your guide, |
| 259 | | visit http://www.google.com/analytics/ to sign up for a key. The answer to |
| 260 | | this question is the string in quotes in the HTML fragment they ask you to |
| 261 | | paste into your HTML, something along the lines of _uacct = "UA-1234567-1" |
| 262 | | - it's the UA-1234567-1 part that you need to put in here. If you've |
| 263 | | forgotten your key, go to Analytics Settings, click "Edit" under Settings, |
| 264 | | then click "Check Status" in the top right-hand corner of the box with grey |
| 265 | | stripes. |
| 266 | | |
| 267 | | |
| 268 | | "What licence will you use for the guide?" |
| 269 | | |
| 270 | | We strongly recommend that you think at the outset about the licence your |
| 271 | | guide will use, for maximum usefulness. In particular for a guide that will |
| 272 | | be on the OpenGuides network, we recommend the |
| 273 | | "Creative Commons Attribution-ShareAlike 2.5" licence. |
| 274 | | |
| 275 | | "What is the URL to your licence?" |
| 276 | | |
| 277 | | If you used our recommendation above the URL you will want here is: |
| 278 | | http://creativecommons.org/licenses/by-sa/2.5/ |
| 279 | | |
| 280 | | "What is the URL to your local page about your licensing policy?" |
| 281 | | |
| 282 | | You should probably include a page on your wiki about your local licensing |
| 283 | | policy, but you can leave this blank for now if you don't have one yet. |
| 284 | | |
| 285 | | "What module would you like to use for spam detection? (optional)" |
| 286 | | |
| 287 | | The module you choose should have a method called "looks_like_spam", which |
| 288 | | accepts a hash with content and metadata as keys, and returns true or false |
| 289 | | to the question of whether the edit should be considered to be spam. |
| 290 | | |
| 291 | | "What directory should we install static content (CSS, images, javascript) |
| 292 | | to?" |
| 293 | | |
| 294 | | OpenGuides comes with some static content which will be installed |
| 295 | | automatically. |
| 296 | | |
| 297 | | "What is the URL corresponding to the static content?" |
| 298 | | |
| 299 | | You will need to configure the above directory in your web server, then |
| 300 | | input the URL the content will be visible at here. |
| 301 | | |
| 302 | | "Should we send email notifications when a moderated node is edited?" |
| 303 | | |
| 304 | | For spam avoidance, you can configure certain nodes to require moderation. |
| 305 | | To ensure that such edits are noticed, OpenGuides can email you. |
| 306 | | |
| 307 | | "Distance calculation methods available are: |
| 308 | | 1) British National Grid |
| 309 | | 2) Irish National Grid |
| 310 | | 3) UTM ellipsoid |
| 311 | | Which would you like to use?" |
| 312 | | |
| 313 | | (and if you choose UTM ellipsoid) |
| 314 | | "Which ellipsoid would you like to use? (eg 'Airy', 'WGS-84')" |
| 315 | | |
| 316 | | See http://www.vterrain.org/Projections/ for how this all works. |
| 317 | | A UTM (Universal Transverse Mercator) ellipsoid maps latitude and |
| 318 | | longitude to eastings and northings on a square grid, which allows |
| 319 | | more accurate distance calculations within the guide. The British and |
| 320 | | Irish National Grids are scaled and parametrised versions of UTM |
| 321 | | ellipsoids (Airy 1830 in the British case, Modified Airy in the Irish). |
| 322 | | |
| 323 | | Please note that at the moment there is no provision for changing your |
| 324 | | mind later about which ellipsoid to use, but it shouldn't be too hard |
| 325 | | to write a conversion script so don't worry too much about picking the |
| 326 | | wrong one. However do note that once you've entered some location |
| 327 | | data you should not change this value in the config file without running |
| 328 | | some kind of converter. |
| 329 | | |
| 330 | | If you decide to use the British or Irish National Grid, your users |
| 331 | | will be able to choose between entering location data as lat/long |
| 332 | | or as grid co-ordinates. |
| 333 | | |
| 334 | | You must have Geography::NationalGrid::GB installed to use the British |
| 335 | | National Grid, Geography::NationalGrid::IE to use the Irish National |
| 336 | | Grid, and Geo::Coordinates::UTM to use a UTM ellipsoid. |
| 337 | | |
| 338 | | If you want to use a UTM ellipsoid, WGS-84 is the best choice, as it |
| 339 | | will allow you to use the Google Maps support with the minimum of fuss. |
| 340 | | |
| 341 | | * Dependency errors |
| 342 | | |
| 343 | | If, after you have answered these questions, the build script complains |
| 344 | | about missing dependencies, don't panic! Simply install them from CPAN and |
| 345 | | then try again. Note that a wiki.conf file will have been written out at |
| 346 | | this point, so if you retain it you won't have to answer all the questions |
| 347 | | again. |
| 348 | | |
| 349 | | * Custom templates and CSS |
| 350 | | |
| 351 | | Once you have installed OpenGuides you may wish to edit templates that |
| 352 | | provide site-specific design. These templates are stored in the directory |
| 353 | | custom-templates/ by default and are described in the file CUSTOMISATION. |
| 354 | | |
| 355 | | The id and class tags used for the CSS in OpenGuides are specified in |
| 356 | | README.CSS. |
| 357 | | |
| 358 | | * Security |
| 359 | | |
| 360 | | The installer will try to create (or modify an existing) a .htaccess file |
| 361 | | to protect wiki.conf, which contains sensitive data (ie passwords). |
| 362 | | However we cannot tell whether apache (or any other web server you may be |
| 363 | | using) is using this file, so you should check that it functioning and that |
| 364 | | you cannot access wiki.conf over HTTP. |
| 365 | | |
| 366 | | You should also configure wiki.conf with the minimum permissions required |
| 367 | | so that local users cannot read the file. This is difficult to automate, |
| 368 | | but the file should be probably be mode 0640, owned by root or an admin |
| 369 | | user, and set to the group the web server runs with. |
| 370 | | |
| 371 | | * Web server configuration |
| 372 | | |
| 373 | | In order to let your web server serve up OpenGuides correctly, you will |
| 374 | | have to tell it to recognise your installation directory as one |
| 375 | | containing CGI scripts. However you can make your URLs nicer by |
| 376 | | employing mod_rewrite as well. The following Apache configuration |
| 377 | | directives show how: |
| 378 | | |
| 379 | | Alias /myguide /usr/lib/cgi-bin/myguide |
| 380 | | <Directory /usr/lib/cgi-bin/myguide> |
| 381 | | Options FollowSymLinks Indexes ExecCGI |
| 382 | | RewriteEngine on |
| 383 | | RewriteBase /myguide/ |
| 384 | | RewriteRule ^$ wiki.cgi [L] |
| 385 | | </Directory> |
| 386 | | Redirect /cgi-bin/myguide/ http://www.example.com/myguide/ |
| 387 | | |
| 388 | | You will of course need to make the appropriate substitutions for |
| 389 | | your site. You also need to make sure that mod_rewrite is enabled in |
| 390 | | your web server before adding such a configuration. The final step in |
| 391 | | this URL tidying is to tell OpenGuides that the main CGI script can be |
| 392 | | assumed to be called from the root of the install directory; do this by |
| 393 | | setting the script name to be empty in wiki.conf: |
| 394 | | |
| 395 | | # what do you want the script to be called? |
| 396 | | script_name = |
| 397 | | |
| 398 | | Currently the Build script does not support this value, so you will |
| 399 | | have to make sure that you fix this up after an upgrade. |
