Personal wiki notebook (not under development)


  1. If you just want to create a wiki online, please see the included README
  2. file instead of this INSTALL file. This file contains details about
  3. installing Luminotes Desktop and Luminotes Server, which you shouldn't
  4. need if you only want to make a wiki.
  5. Luminotes Desktop
  6. =================
  7. Luminotes Desktop allows an individual to take notes on their own
  8. computer without an internet connection.
  9. First, install the prerequisites:
  10. * Python 2.4 to 2.5
  11. * CherryPy 2.3
  12. * pysqlite 2.3 to 2.4
  13. * simplejson 1.3 to 2.0
  14. * pytz 2006p to 2008c
  15. * Python Imaging Library 1.1
  16. * Python Universal Encoding Detector 1.0
  17. In Debian GNU/Linux or Ubuntu, you can issue the following command to install
  18. these packages:
  19. apt-get install python python-cherrypy python-pysqlite2 \
  20. python-simplejson python-tz python-imaging python-chardet
  21. database setup
  22. --------------
  23. Initialize the database with the starting schema and default data. You should
  24. run this command from the base Luminotes directory:
  25. export PYTHONPATH=.
  26. python tools/ -l
  27. running Luminotes Desktop
  28. -------------------------
  29. To start Luminotes, run:
  30. python -l
  31. This will run the local Luminotes web server and automatically launch a web
  32. browser so you can use Luminotes. You don't need to create an account or
  33. login. Just start creating a wiki.
  34. If Luminotes is already running when you invoke that command, it will just
  35. open a new web browser window to connect to the existing Luminotes
  36. server on the correct port.
  37. In case you're curious, your notes and attached files are stored in the
  38. ~/.luminotes directory.
  39. If you'd like to run Luminotes from a USB drive, first install Luminotes
  40. Desktop normally. Once it's installed, instead of running Luminotes, manually
  41. copy the entire Luminotes directory to a USB drive. Then, run
  42. tools/ from the USB drive. Your Luminotes data, including all
  43. of your notes and notebooks, will be stored on the USB drive instead of on the
  44. computer itself. Then, anytime you want to start Luminotes on the USB drive,
  45. run from it.
  46. If you're only interested in running Luminotes Desktop, you can stop reading
  47. here.
  48. building Luminotes Desktop
  49. --------------------------
  50. If you'd like to build your own Luminotes installer for Windows, follow these
  51. steps. You should only need to do this if you are a Luminotes developer.
  52. Otherwise you can completely skip this section.
  53. First, install the prerequisites:
  54. * Python 2.4 to 2.6
  55. * setuptools 0.x
  56. * CherryPy 2.3
  57. * pysqlite 2.x (which wraps SQLite 3.x)
  58. * simplejson 1.3
  59. * pytz 2006p to 2008c
  60. * Python Imaging Library 1.1
  61. * Python Universal Encoding Detector 1.0
  62. * Microsoft Visual C++ 2008 SP1 Redistributable Package
  63. (You do not need Visual Studio itself.)
  64. * py2exe 0.x
  65. * Inno Setup Unicode 5.x
  66. * Luminotes source code
  67. The recommended way to do this on Windows is as follows:
  68. 1. Log into Windows as the Administrator.
  69. 2. Install Python via the official Windows installer.
  70. 3. Install setuptools by downloading and running
  71. 4. Install CherryPy. Since Luminotes currently requires an ancient version of
  72. CherryPy, install it manually by downloading the correct version and
  73. running: python.exe install within CherryPy's unzipped directory.
  74. Note: python.exe is usually found in C:\Python*\
  75. 5. Install other packages with easy_install (or pip, if you prefer):
  76. * easy_install.exe install pysqlite
  77. * easy_install.exe install simplejson
  78. * easy_install.exe install pytz
  79. * easy_install.exe install pil
  80. * easy_install.exe install chardet
  81. Note: easy_install.exe is usually found in C:\Python*\Scripts\
  82. 7. Install Visual C++ 2008 SP1 Redistributable Package via its installer.
  83. 8. Install py2exe via its installer.
  84. 9. Install Inno Setup Unicode via its installer.
  85. 10. Download and unpack the Luminotes source code.
  86. To actually build the Luminotes Desktop installer, open a command shell and cd
  87. to the Luminotes source directory. Then run:
  88. python.exe py2exe
  89. ISCC.exe dist\luminotes.iss
  90. Note: ISCC.exe is usually found in C:\Program Files\Inno Setup 5\
  91. If py2exe has problems importing certain packages that are installed as eggs,
  92. then try unzipping the eggs into directories of the same name. The eggs are
  93. usually found in C:\Python*\Lib\site-packages\
  94. The commands above should produces a Luminotes Desktop setup.exe installer
  95. within the dist\Output\ directory. You can the run setup.exe on any Windows
  96. computer to install Luminotes Desktop.
  97. Luminotes Server
  98. ================
  99. Luminotes Server allows a team to set up their own Luminotes web server, just
  100. like at
  101. First, install the prerequisites:
  102. * Python 2.4 to 2.5
  103. * CherryPy 2.3
  104. * PostgreSQL 8.1
  105. * psycopg 2.0
  106. * simplejson 1.3
  107. * pytz 2006p to 2008c
  108. * Python Imaging Library 1.1
  109. * Python Universal Encoding Detector 1.0
  110. In Debian GNU/Linux or Ubuntu, you can issue the following command to install
  111. these packages:
  112. apt-get install python python-cherrypy postgresql-8.1 \
  113. postgresql-contrib-8.1 python-psycopg2 python-simplejson \
  114. python-tz python-imaging python-chardet
  115. database setup
  116. --------------
  117. Configure PostgreSQL's pg_hba.conf (usually found under /etc/postgresql/) to
  118. require passwords for local connections:
  119. local all all md5
  120. Restart postgresql so these changes take effect:
  121. /etc/init.d/postgresql restart
  122. As the PostgreSQL superuser (usually "postgres"), create a new database user
  123. and set a new password, for instance, "mypassword".
  124. createuser -S -d -R -P -E luminotes
  125. createdb -E UTF8 -O luminotes luminotes
  126. Also as the PostgreSQL superuser, setup full-text searching. The path to the
  127. tsearch2.sql file may be different depending on your Linux distribution or
  128. PostgreSQL version, and is usually found within a PostgreSQL "contrib"
  129. package:
  130. psql luminotes < /usr/share/postgresql/8.1/contrib/tsearch2.sql
  131. echo "grant all on pg_ts_cfg to luminotes;" | psql luminotes
  132. echo "grant all on pg_ts_cfgmap to luminotes;" | psql luminotes
  133. echo "grant all on pg_ts_dict to luminotes;" | psql luminotes
  134. echo "grant all on pg_ts_parser to luminotes;" | psql luminotes
  135. echo "update pg_ts_cfg set locale = 'en_US.UTF-8' where ts_name = 'default';" | psql luminotes
  136. echo "create language plpgsql;" | psql luminotes
  137. Note that you can use a different UTF-8 locale if you prefer. For instance, in
  138. the command above, you can use 'en_GB.UTF-8' instead of 'en_US.UTF-8'.
  139. Initialize the database with the starting schema and default data. You should
  140. run this command from the base Luminotes directory:
  141. export PYTHONPATH=.
  142. export PGPASSWORD=mypassword
  143. python tools/
  144. development mode
  145. ----------------
  146. Running the Luminotes server in development mode is convenient for testing out
  147. changes, because it uses CherryPy's built-in web server with auto-reload
  148. enabled, so the server will automatically reload any modified source files as
  149. soon as they're modified.
  150. To start the server in development mode, run:
  151. python -d
  152. Connect to the following URL in a web browser running on the same machine:
  153. http://localhost:8081/
  154. production mode setup
  155. ---------------------
  156. Production mode is intended for a live production web site, so you can skip
  157. this section entirely if you don't care about running such a site. Production
  158. mode doesn't support auto-reload, and logging goes to file (luminotes.log)
  159. instead of the console, but performance should be better than in development
  160. mode.
  161. First you'll need to configure your web server to forward requests for pages
  162. to Luminotes. Example configuration files are included for both Apache and
  163. nginx, but in theory, Luminotes should work with just about any web server.
  164. For Apache, enable mod_rewrite and mod_proxy, and then configure a VirtualHost
  165. as per the example configuration file in examples/apache_luminotes.
  166. For nginx, if you want a working upload progress bar, build and install a
  167. version of nginx with the NginxHttpUploadProgressModule enabled. See:
  168. for more
  169. information. Then, configure nginx as per the example configuration file in
  170. examples/nginx_luminotes.
  171. Also for nginx, you should edit config/ and set the
  172. luminotes.web_server value to "nginx" so that Luminotes makes use of nginx's
  173. X-Accel-Redirect header. For instance:
  174. "luminotes.web_server": "nginx",
  175. For either web server, you should change the paths in your configuration file
  176. to point to wherever Luminotes happens to be installed. The example
  177. configuration causes your web server to serve static files itself, while
  178. passing through requests for dynamic pages to the Luminotes web server running
  179. locally.
  180. Additionally, you should let Luminotes know about the public hostname of
  181. your web site. Simply edit config/ and change the value of
  182. luminotes.http_url based on the domain you're using. For instance:
  183. "luminotes.http_url": "",
  184. SSL support
  185. -----------
  186. If you want to use SSL, procure and install an SSL cert for use with your web
  187. server. Duplicate the standard non-SSL web server configuration for a separate
  188. SSL-enabled VirtualHost or server section, but change the IP address from
  189. to for SSL. This hack allows the Luminotes server to
  190. distinguish between SSL and non-SSL requests by looking at the proxy IP.
  191. Without this, Luminotes would have no way of knowing whether a particular
  192. request was encrypted when received by your web server. (There are ways to do
  193. this in a less hacky manner, which might be supported in the future.)
  194. To configure the Luminotes server for SSL support, edit config/
  195. and change the value of luminotes.https_url based on the domain you're
  196. using. For instance:
  197. "luminotes.https_url": "",
  198. starting production mode
  199. ------------------------
  200. Then to actually start the production mode server, run:
  201. python
  202. You should be able to connect to the site at whatever domain you've configured
  203. Apache or nginx to serve.
  204. Optionally, you can copy examples/luminotes_debian_initscript to
  205. /etc/init.d/luminotes and use the following command to start the Luminotes
  206. server instead:
  207. /etc/init.d/luminotes start
  208. sending email
  209. -------------
  210. If you would like Luminotes to be able to send password reset emails, then
  211. you'll need a mail server running on the same machine that is capabable of
  212. receiving local SMTP connections and sending email. Either way, please set
  213. the luminotes.support_email address in config/ to the email address
  214. you'd like in the From field of all outgoing emails. This email address also
  215. shows up in various error messages and other places for a support contact
  216. address.
  217. user rate plans
  218. ---------------
  219. By default, all Luminotes users start at rate plan 0. This corresponds to the
  220. Luminotes "free" account level described at
  221. If you'd like to change the details of any of the rate plans, edit
  222. config/ and change the first listed plan under luminotes.rate_plans.
  223. For instance, if you'd like users at rate plan 0 to be allowed to invite other
  224. users to edit their notebooks, change the "notebook_collaboration" value to
  225. "True". If you like, you can also increase the amount of storage they're
  226. allowed.
  227. memcached
  228. ---------
  229. For improved performance, it is recommended that you install and use memcached
  230. for production servers.
  231. First, install the prerequisites:
  232. * python-dev 2.4 or 2.5
  233. * libmemcache-dev 1.4
  234. * memcached 1.4
  235. * cmemcache 0.95
  236. In Debian GNU/Linux or Ubuntu, you can issue the following command to install
  237. these packages:
  238. apt-get install python-dev libmemcache-dev memcached
  239. The cmemcache package is not currently included with Debian or Ubuntu, so
  240. you'll have to build and install it manually. Download and untar the package
  241. from:
  243. From the untarred cmemcache directory, issue the following command as root:
  244. python install
  245. This should build and install the cmemcache module. Once installed, Luminotes
  246. will use the module automatically. When Luminotes starts up, you should see a
  247. "using memcached" message.
  248. Python unit tests
  249. -----------------
  250. If you're interested in running unit tests, install:
  251. * nose 0.9.0
  252. In Debian GNU/Linux or Ubuntu, you can issue the following command to install
  253. this packages:
  254. apt-get install python-nose
  255. Then you can run unit tests by running:
  256. nosetests
  257. search performance
  258. ------------------
  259. If you have many notes in your database and/or many users, you may find that
  260. wiki searching is too slow. If that's the case, you can try modifying the way
  261. that notes are indexed for searching in the database.
  262. These changes are completely optional and fairly technical, and you can safely
  263. ignore them for the majority of Luminotes Server installations.
  264. First, download an English ispell dictionary from this site:
  266. Untar the tarball and put the two english.* files into a convenient location
  267. such as /usr/local/lib/ispell
  268. Then, at a psql prompt for the luminotes database, run the following SQL
  269. command to tell PostgreSQL's tsearch2 module about the new dictionary files:
  270. insert into pg_ts_dict (
  271. select
  272. 'en_ispell',
  273. dict_init,
  274. 'DictFile="/usr/local/lib/ispell/english.dict",'
  275. 'AffFile="/usr/local/lib/ispell/english.aff",'
  276. 'StopFile="/usr/share/postgresql/8.1/contrib/english.stop"',
  277. dict_lexize
  278. from pg_ts_dict
  279. where dict_name = 'ispell_template'
  280. );
  281. You may have to change the paths if you put the english.* files in a different
  282. location, or if your PostgreSQL installation has the english.stop file in a
  283. different location.
  284. Next, run the following commands at the psql prompt to make PostgreSQL use the
  285. new dictionary for searches by default:
  286. update
  287. pg_ts_cfgmap set dict_name = null where ts_name = 'default' and
  288. dict_name = '{simple}';
  289. update
  290. pg_ts_cfgmap set dict_name = '{en_ispell,en_stem}'
  291. where
  292. dict_name = '{en_stem}' and ts_name = 'default';
  293. The second command should update about three rows.
  294. To test whether the new dictionary is working, run the following command:
  295. select lexize('en_ispell', 'program');
  296. You should see a result like the following:
  297. lexize
  298. -----------
  299. {program}
  300. (1 row)
  301. If you don't see "{program}" in the result, PostgreSQL may not be finding your
  302. english.* dictionary files, so check the paths and try again.
  303. Lastly, regenerate the database indices used for searching. This may take a
  304. while:
  305. drop trigger search_update on note_current;
  306. drop index note_current_search_index;
  307. update
  308. note_current set search = to_tsvector('default',
  309. coalesce(title,'') ||' '|| coalesce(contents,'') );
  310. vacuum full analyze;
  311. create index note_current_search_index on note_current USING gist (search);
  312. vacuum full analyze;
  313. create trigger search_update
  314. before insert or update on note_current
  315. for each row
  316. execute procedure tsearch2('search', 'drop_html_tags', 'title',
  317. 'contents');
  318. For a much more thorough treatment of using custom dictionaries with tsearch2,
  319. read the "Tsearch V2 Introduction" on the aforementioned web page.