TightURL

TightURL Git Source Tree

Root/INSTALL

1 TightURL
2 Installation
3 version 0.1.3.2
4
5 Installing TightURL
6 -------------------
7
8 1. Untar the file: tar zxvf tighturl-0.1.3.2.tar.gz or
9 unzip the file: unzip tighturl-0.1.3.2.zip
10
11 2. Move the files in the directory to where you want to run
12 your installation of TightURL.
13
14 3. Rename tighturl.php to index.php if desired. (highly desirable!)
15
16 4. A. New installations should move the contents of the ./local directory
17 into the main TightURL directory.
18 B. Upgrades should review the contents of ./local and adjust existing
19 config file and templates as seen fit. Things probably won't work
20 correctly unless you modify the tighturl.config.inc in ./local with
21 your desired settings and use that.
22
23 5. New installations should create a MySQL database and user if
24 necessary. If you don't know how, (we were all beginners once) it
25 goes something like this:
26 mysql -u root -p
27 Enter password: **********
28 mysql> create database tighturl;
29 mysql> quit
30
31 If you also need to add a MySQL user (you should never use "root"),
32 then before you quit MySQL, you should enter a command like this:
33
34 mysql> grant all on dbname.* to dbuser@localhost identified by 'pass';
35
36 substituting the name of your database for "dbname", the name of the
37 MySQL user you want to create for "dbuser", and the desired password
38 in place of "pass".
39
40 6. Edit the config settings in tighturl.config.inc.php as needed.
41 New installs will need to change at least the MySQL database settings.
42 See 'Configuration Settings' below.
43
44 7. Run the script: tighturl-install.php
45 When this is done, you will need to remove or rename this script
46 before your TightURL installation will work.
47
48 8. If you can set a custom 404 page for your Web site/directory, you
49 can set it to tighturl/index.php and get shorter URLs. To take
50 advantage of this, set $FOFMethod=TRUE in tighturl.config.inc.php.
51
52 9. Change the $svcname in tighturl.config.inc.php if desired.
53
54 10. Edit the master site HTML template tighturl.tmpl if desired.
55 See 'TightURL Templates' below.
56
57 11. Edit the HTML sub-templates if desired. These are:
58 A. tighturl.main.tmpl : HTML shown for your TightURL homepage
59 B. tighturl.save.tmpl : HTML shown when a URL is saved
60 C. tighturl.help.tmpl : HTML shown for Help info (may not exist yet)
61 D. tighturl.faq.tmpl : HTML shown for FAQ (may not exist yet)
62 D. tighturl.blacklist.tmpl : HTML shown for blacklisted URL submissions
63 D. tighturl.policy.tmpl : HTML shown for URL submissions that violate
64 your local policy.
65
66 See 'TightURL Templates' below for more information.
67
68 Configuration Settings
69 ----------------------
70
71 These are the configuration (variables) settings that can and should
72 be changed in tighturl.config.inc.php :
73
74 MySQL:
75 $dbhost : DNS name of your MySQL server
76 $dbuser : MySQL user name
77 $dbpass : password for MySQL user name
78 $dbname : database containing TightURL's table
79 $dbtable : name of TightURL's table
80
81 Operating modes:
82 $FOFMethod : Use 404-Method or mod_rewrite to compress TightURLs
83 0 (FALSE) = full URL path (not compressed) TightURLs
84 1 = 404-Method compressed TightURLs
85 2 = mod_rewrite compressed TightURLs
86
87 URIBL variables:
88 $uribl : Array of URIBLs to check
89 $uriblurl : Array of Web sites corresponding to URIBLs checked
90
91 Text strings and style variables:
92 $svcname : One-word name for your TightURL service
93 $verbtext : One-word name for the act of tightening URLs
94 $pasttext : Past-tense name for a tightended URL
95 $tagline : "tag line" for your TightURL service
96 $headcolor : Color for the TightURL <H1> HTML header
97 $tablecolor : Color for the table the URL input field appears in
98 $copystart : 4-digit year of start of your copyright on your content.
99 defaults to current year if not given.
100
101 NEVER CHANGE SETTINGS IN tighturl.php OR YOU WILL LOSE YOUR CHANGES
102 any time you upgrade to a newer version of TightURL. Always put your
103 configuration settings in tighturl.config.inc.php where they will
104 survive upgrades. Values in tighturl.config.inc.php override the
105 defaults (garbage) in tinyurl.php .
106
107 Reserved URLs
108 -------------
109
110 Because we use Base-36 numbers as TightURL IDs, as time goes on,
111 certain desirable URLs will be issued that we might want to keep
112 for ourselves.
113
114 For instance, the letters 'faq' are well-understood around the Internet
115 to mean "Frequently Answered Questions". We might want to use the URL
116 http://example.com/faq to point to our FAQ page, rather than issue it
117 as a regular TightURL to a random visitor. Reserved URLs allow you to
118 specify Base-36 IDs that should never be issued as TightURLs.
119
120 There are two kinds of Reserved URLs. External (implicit) and Internal
121 (explicit) Reserved URLs.
122
123 External Reserved URLs:
124
125 Any URL which exists in your Web space will be served up by
126 your Web server, and not TightURL. For this reason, any URL
127 reasonably within your TightURL ID space that you want to use
128 with your TightURL site itself should be reserved so that you
129 don't issue a TightURL to anyone that won't actually work.
130
131 For example, if you have a directory named: /www/example.com/faq
132 your Web server will attempt to serve index.html from within
133 that directory, and TightURL will never even see the request.
134 This kind of reservation is implicit, and TightURL must be
135 made aware of it.
136
137 Internal Reserved URLs:
138
139 Any URL which does not exist in your Web space but is Reserved
140 within TightURL will cause TightURL to look for a correspondingly
141 named TightURL Template, and serve that. If the template does
142 not exist, a 404 error is generated.
143
144 For example, if you have reserved the ID 'faq', and TightURL
145 sees a request for this reserved ID, it will attempt to open a
146 template named tighturl.faq.tmpl and return that to the browser.
147
148 It is VERY IMPORTANT that you decide what your Reserved URLs will be
149 before your TightURL service is put into operation, or else you run
150 the risk of wanting to reserve a URL that's already been issued as
151 a TightURL to someone. For example, by the time you've issued your
152 19826th TightURL, you will have lost the opportunity to use 'faq' as
153 a Reserved URL, because decimal (Base-10) number '19826' is number
154 'faq' in sexigesimal (Base-36).
155
156 Reserving URLs:
157
158 To reserve a URL, add it to the configuration array $ReservedURL .
159 The following URLs are reserved by default:
160
161 faq, help, code, source, docs, cvs, arch, url,
162 about, admin, setup, svn
163
164 There is little point in reserving URLs larger than 5 charcters long.
165 The first 6 character ID is '100000' sexigesimal, which would be far
166 past your 60 millionth TightURL issued. Since each additional Reserved
167 URL adds a little more processing time, you don't want to add URLs
168 that will never be issued anyway.
169
170 TightURL presently uses the ID "api" with the template that describes
171 how to use the TightURL API. It would be the 13878th TightURL in the
172 system, which can easily be achieved on a moderately-used corporate-
173 wide TightURL installation.
174
175 TightURL Templates
176 ------------------
177 TightURL supports a simple variable-substitution templating system with
178 one level of template nesting.
179
180 The outer template is *always* the main site template, tighturl.tmpl .
181 This template controls your site design and is *always* used to generate
182 output pages to the browser.
183
184 The inner template is *always* one of the following sub-templates
185 (or no sub-template):
186 tighturl.main.tmpl : HTML shown for your TightURL homepage
187 tighturl.save.tmpl : HTML shown when a URL is saved
188 tighturl.help.tmpl : HTML shown for Help info (may not exist yet)
189 (none) : No inner template.
190
191 Please note that many screens are generated using only the main site
192 (outer) template. All error screens are generated this way.
193
194 The variables supported by TightURL Templates are:
195
196 $HTML : In the innermost or only template, replaced by a HTML
197 message from TightURL. In an outer template, it is
198 replaced by contents of the inner (sub-)template.
199 You should never remove this variable from a template.
200 $PARM : Parameter when 404-Method not used.
201 $URL : Replaced by browser submitted URL.
202 $URLLEN : Replaced by lenghth of the submitted URL.
203 $TIGHTURL : Replaced by TightURL generated by the submission.
204 $TIGHTURLLEN : Replaced by length of the generated TightURL.
205 $DIFF : Replaced by difference in length between URLs.
206 $INPUT : Replaced by submitted URL for use when there has
207 been an error detected in the input.
208 $SVCNAME : Replaced by name chosen for your TightURL service.
209 $HEADCOLOR : Replaced by color value chosen for <H1> HTML tags.
210 $TABLECOLOR : Replaced by color value chosen for the table.
211 $TAGLINE : Replaced by "tag line" for your TightURL service.
212 $CPASTTEXT : Replaced by capitalized past tense description of
213 tightened URLs.
214 $PASTTEXT : Same as $CPASTTEXT, but first letter not capitalized.
215 $CVERBTEXT : Replaced by capitalized verb description of your
216 TightURL service.
217 $VERBTEXT : Same as $CVERBTEXT, but first letter not capitalized.
218 $COPYRIGHT : Replaced by generated copyright string created from
219 $copystart config value and current year.
220 $URIBLS : Replaced by HTML showing URIBLs being checked.
221 $HOST : Replaced by hostname of Web site.
222 $SELF : Replaced by the URL path to the TightURL script.
223 $BBSTATS : Replaced by Bad Behavior stats when BB2 is enabled.
224 $TIGHTURLVER : Replaced by the TightURL running version number.
225
226 TightURL Operating Modes
227 ------------------------
228
229 TightURL supports three distinct "operating modes". These are known as
230 "basic", "mod_rewrite", and "404 Method". You want to avoid changing your
231 operating mode later, as changes to or from basic mode will cause all your
232 URLs to change. Changes between mod_rewrite and the 404 Method do not
233 result in changes to your URLs, but your operating mode is something you
234 should choose carefully and then stick with.
235
236 Using basic mode
237 ----------------
238
239 This operating mode produces URLs that follow this pattern:
240 http://example.com/?i=id or http://example.com/yoursite/?i=id
241
242 No changes to httpd.conf or .htaccess are required for basic mode, but
243 this produces slightly longer and more inconvenient to type URLs. If you
244 can use mod_rewrite or the 404 Method, it is highly recommended that you
245 do so.
246
247
248 Using mod_rewrite with Apache
249 -----------------------------
250
251 PLEASE NOTE: There was a longstanding bug in Apache mod_rewrite that
252 probably makes TightURL or anything like it unable to work except with
253 what are still very recent versions of Apache.
254 https://issues.apache.org/bugzilla/show_bug.cgi?id=34602
255
256 Users are encouraged to use "404 Mode", and especially in the event
257 their Apache version has the bug shown above.
258
259
260 This operating mode produces URLs that follow this pattern:
261 http://example.com/id or http://example.com/yoursite/id
262
263 TightURL can be used with mod_rewrite by adding the following lines to
264 httpd.conf or if you can't modify httpd.conf, you can use .htaccess :
265
266 <IfModule mod_rewrite.c>
267 RewriteEngine On
268 RewriteRule ^view/([a-z0-9-]+)/?$ index.php?v=$1 [NC,L]
269 RewriteRule ^([a-z0-9-]+)/?$ index.php?i=$1 [NC,L]
270 </IfModule>
271
272 If you change the parameters (form variables) from "i" for the TightURL ID
273 to look up, and "v" for the TightURL ID to preview, then you'll need to
274 adjust these lines accordingly.
275
276 Be aware that http.conf is read once when the Web server is started or
277 reloaded, but .htaccess must be read and parsed for *every request*, so
278 you always want to use http.conf over .htaccess whenever possible.
279
280
281 Using "The 404-Method" with Apache
282 ----------------------------------
283
284 This operating mode produces URLs that follow this pattern:
285 http://example.com/id or http://example.com/yoursite/id
286
287 The "404-Method" refers to instructing your Web server to direct all
288 requests that generate a "Not found" error (which is an HTTP error code
289 404) to the TightURL script. By doing this, TightURL will run for URLs in
290 your TightURL site that don't exist, such as would be the case for
291 http://example.com/tighturl.php/xxyy
292
293 The xxyy is a TightURL ID number, not an actual Web page in your site. By
294 sending non-existent page requests to the TightURL script, you can look up
295 those IDs and issue an HTTP Redirect without the need for mod_rewrite.
296
297 To use the 404-Method, set $FOFMethod=1 in tighturl.config.inc.php.
298
299 Using .htaccess
300 ---------------
301
302 Then put this in your .htaccess file:
303
304 ErrorDocument 404 /index.php
305
306 This change should take effect immediately after saving .htaccess .
307 If it doesn't work, make sure you have AllowOverride FileInfo on in the
308 directory you're running TightURL from.
309
310 Using httpd.conf
311 ----------------
312
313 Alternatively to using .htaccess (and for improved performance), put the
314 following line in your httpd.conf in the appropriate Directory section
315 (and VirtualHost if applicable):
316
317 ErrorDocument 404 /index.php
318
319 You will need to reload your Apache configuration for this change to take
320 effect.
321
322 See the Apache documentation for more information.
323 http://httpd.apache.org/docs/mod/core.html#errordocument
324 http://httpd.apache.org/docs/mod/core.html#allowoverride
325
326
327 AntiAbuse: Generally if your web site is connected to the Internet and
328 and the TightURL library can make outbound network connections, you should
329 run with the antiabuse system turned on. When the antiabuse system is
330 turned off, virtually everything will be accepted into your database that
331 can be shortened.
332
333 NetChecks: Generally if your web site is connected to the Internet and
334 and the TightURL library can make outbound network connections, you should
335 run with the netchecks system turned on. If your site has no connectivity
336 or ability to make outbound network connections, you should turn the
337 netchecks off. When netchecks are off, TightURL will not be able to resolve
338 URLs through redirections to their final destination, check for new versions
339 of TightURL, or check submitted URLs against URI blacklists.
340
341
342 Adding more URIBLs
343 ------------------
344
345 In the event other URIBLs beside SURBL become available, and you wish
346 to check those also, edit $uribl and $uriblurl in
347 tighturl.config.inc.php .
348
349 To add a new URIBL named uribl.example.com whose Web site is located
350 at http://www.example.com
351
352 Change this:
353
354 $uribl = array("multi.surbl.org");
355 $uriblurl = array("www.surbl.org");
356
357 To this:
358
359 $uribl = array("multi.surbl.org","uribl.example.com");
360 $uriblurl = array("www.surbl.org","www.example.com");
361
362 You can add as many URIBLs as you want this way.
363
364 Squeezing Your Base URL Down to the Smallest Possible Size
365 ----------------------------------------------------------
366 The "base URL" is the fixed portion of your TightURL URLs. This
367 would be everything up to the TightURL ID at the end of the URL.
368 The length of the TightURL ID will start out at 1 character and may
369 get up to 6 characters after tens of millions of TightURLs have been
370 created in your system. (Most TightURL installations are not
371 expected to get into the tens of thousands, let alone tens of
372 millions) Because the ID is at most 6 characters, the most
373 important thing you can do to get the shortest URL possible is to
374 "squeeze" as many characters out of the base portion of the URL
375 as possible.
376
377 The following URL is "unfortunately long", but should still allow
378 you to create tens of millions of TightURLs that can be used without
379 wrapping in most e-mail programs. It is 72 characters long:
380
381 http://www.a-really-quite-long-name.com/~example01/tighturl.php?i=abcdef
382
383 This URL is not only unfortunately long, it is unnecessarily long
384 as well. The following optimizations can be attempted:
385
386 1. Drop the "www."
387 2. Rename tighturl.php to something shorter.
388 3. Rename tighturl.php to index.php and put it in a 1-character subdir.
389
390 If optimizations 1 and 3 are successfully applied, we get a 58
391 character URL (14 characters shorter):
392
393 http://a-really-quite-long-name.com/~example01/t/?i=abcdef
394
395 A more optimistic domain name (39 characters):
396
397 http://example.com/~example/t/?i=abcdef
398
399 Ideal scenario with own domain (29 characters):
400
401 http://tighturl.com/?i=abcdef
402
403 If you are able to use Mod_Rewrite or the 404-Method as shown
404 above, you can also drop the "?i=" portion of the URL, saving
405 another 3 characters.
406
407 Mod_Rewrite or 404-Method scenario (26 characters):
408
409 http://tighturl.com/abcdef
410
411 This also works with the "unfortunately long" URL, bringing
412 it down to 56 characters:
413
414 http://a-really-quite-long-name.com/~example01/t/abcdef
415
416********************************************************************************

Archive Download this file

Branches