couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <>
Subject [Couchdb Wiki] Update of "Quirks_on_Windows" by DaveCottlehuber
Date Sat, 05 Mar 2011 10:27:33 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Couchdb Wiki" for change notification.

The "Quirks_on_Windows" page has been changed by DaveCottlehuber.
The comment on this change is: Improve notes on installer and erlsrv details to help people
rebundle CouchDB in their own apps. Clean Bit Rot..


   * run the latest [[|couchapp installer]]
   * sign yourself up for the current free no-guarantees [[|beta
cloud hosting]] to get your own couch ready to go
   * read the [[|quick start notes]]
on using [[|CouchApp]]
-  * wade into [[|the Definitive Guide]]
+  * wade into [[|the Definitive Guide]]
  == Run ==
+  * you will likely wish to modify %COUCHDB%\etc\couchdb\local.ini with more appropriate
details for IP address & server port (in the [httpd] section), or adjust the log file
levels (in [log])
+  * your CouchDB data files are stored in %OCUCHDB%\var\lib\couchdb\
+  * log files are stored in %OCUCHDB%\var\log\couchdb\
+  * these locations can be modified however if you duplicate the relevant [couchdb] section
from %COUCHDB%\etc\couchdb\default.ini into local.ini as above
   * the crash-safe storage engine means you can hibernate or reboot at will without data
   * VSS snapshots for backup are a really good way to go
   * Firefox is the only supported browser for the test suite, but for almost anything else
a current version of IE will work "just fine". YMMV
@@ -26, +29 @@

   * cURL works just fine on Windows -- once you understand the unwritten rules of quotes
which are very different to that on Unix. The standard example from CouchDB the Definitive
Guide will fail with a "Invalid UTF-8 JSON" error
- curl-X PUT http://username:password@localhost:5984/albums/6e1295ed6c29495e54cc05947f18c8af
-d '{"title":"There is Nothing Left to Lose","artist":"Foo Fighters"}'
+ curl -H "Content-Type: application/json" -X PUT http://username:password@localhost:5984/albums/6e1295ed6c29495e54cc05947f18c8af
-d '{"title":"There is Nothing Left to Lose","artist":"Foo Fighters"}'
   * the 2 alternatives are either to include your JSON-encoded data as a file:
-  curl-X PUT http://username:password@localhost:5984/albums/6e1295ed6c29495e54cc05947f18c8af
-d @foo.json
+  curl -H "Content-Type: application/json" -X PUT http://username:password@localhost:5984/albums/6e1295ed6c29495e54cc05947f18c8af
-d @foo.json
   * or to use one of the three escape character sequences ("" or a ^" or a \") for every
internal quote, to get past the cmd.exe shell
- curl -X PUT http://username:password@localhost:5984/albums/6e1295ed6c29495e54cc05947f18c8af
-d "{\"title\":\"There is Nothing Left to Lose\",\"artist\":\"Foo Fighters\"}"
+ curl -H "Content-Type: application/json" -X PUT http://username:password@localhost:5984/albums/6e1295ed6c29495e54cc05947f18c8af
-d "{\"title\":\"There is Nothing Left to Lose\",\"artist\":\"Foo Fighters\"}"
+ == Building from Source ==
+ Note the full build chain is [[|documented]]
-- but again you don't need this for *installing* and *using* CouchDB on Windows. There are
a number of [[|blog posts]] helping you build from source
if needed.
- == Tools ==
-  * For general usage of CouchDB and the essential [[|CouchApp]] tool,
get the following bits installed & added to your path
-  * in each case we list the tool, site, then the version last tested with in case you get
stuck with version creep
-  * the 32-bit tools are recommended even on 64-bit platforms for the moment.
- ||Tool || WWW || Tested Version ||
- || cURL || ||
- || Python 2.7 || || ||
- || !PyWin32 || ||
- || !SetupTools || ||
- || !RestKit || ||
- || OpenSSL || ||
- || CouchApp || ||
- || CouchDB v1.0.2 on Erlang 14B01 || ||
- == Building from Source  ==
- Note the full build chain is [[|documented]]
-- but again you don't need this for *installing* and *using* CouchDB on Windows. There are
a number of [[|blog posts]]
   * use only 32-bit components even if you are building on a 64-bit architecture
   * make sure you have a clean path with your build chain first - watch out for other developer
tools like git, which may have older versions of OpenSSL or ICU binaries in your path
   * Firefox is the only supported browser for running the Futon test suite - some tests still
fail due to platform differences however
@@ -65, +54 @@

   * this ensures you have a cruft-free experience while both CouchDB, the windows build &
its installer continues to change rapidly
  == Tricks and Traps ==
-  * Online compaction is not supported on Windows due to differences between UX and Windows
on renaming/deleting files that are open in another process/thread. This has been worked around
in 1.0.1 and requires Erlang/OTP 14A. Recent installers have this built in.
-  * if your installed CouchApp.exe doesn't start correctly, you may want to remove two DLLs
from it's folder - KernelBase.DLL and PowrProf.DLL which were present in CouchApp.0.6.exe
and should be removed.
-  * Not much else really since 0.10 if you have any problems feel free to post to the list
for advice.
   * there are some issues still with the windows installer - check [[|Windows_binary_installer]]
for more details
+ == How is CouchDB deployed on Windows? ==
+ A full MSI installer package is not yet available but check back on dev@ for news on this.
The Official CouchDB installer performs 4 main functions:
+  * unpacks itself into the provided folder, including Erlang, CouchDB and javascript DLLs,
and the version of Visual C++ redist used to build Erlang/CouchDB
+  * runs the included matching vcredist_x86.exe package if required
+  * runs "%COUCHDB%\Install.exe -s" to set up Erlang correctly. This involves adding some
registry parameters under HKLM/Software/Ericsson (HKLM/Software/WOW6432Node/Ericcson on 64-bit
Windows), and updating the 2 erl.ini files in %COUCHDB%\bin\ and %COUCHDB%\erts-*\bin respectively.
Erlang and CouchDB will not run if these .ini files have not been created/updated during installation.
+  * optionally running %COUCHDB%\erts-*\erlsrv.exe to set up CouchDB as a service. This alters
further registry parameters.
+ == Integrating CouchDB into your Windows Applications ==
+ From the above, the bare minimum to roll CouchDB into your own application installer follows.
+ === Preparation ===
+  * unpack the official installer into a blank directory. use the same fileset as above,
editing both erl.ini as needed
+  * clean %COUCHDB%\var\lib\couchdb\ and %COUCHDB%\var\log\couchdb\ as required.
+  * you can optionally include a CouchDB database file simply by leaving it in %COUCHDB%\var\lib\couchdb\
+ === Bundling ===
+ You can bundle the app in whatever installer toolkit you prefer. Make sure it does the following,
in order:
+  * set the installer to unpack distribution files
+  * run vcredist first to ensure the following binaries don't simply crash
+  * set up Erlang using "%COUCHDB%\Install.exe -s"
+  * if you need to set up a service, use [[|erlsrv.exe]]
to do so.
+ === Upgrading ===
+ Most recent changes since 0.8 have required a full uninstall and re-install to avoid mixing
Erlang libraries from different versions. Depending on changes in Erlang and CouchDB it may
be that the on-disk format or replication has also changed. You will need to decide how to
handle this on a case-by-case basis. The official CouchDB installer in versions after 1.0.2
will not require a reboot during/after uninstall & reinstall. This is due to killing off
the stray epmd.exe process prior to upgrade/installation.
+ == Inside CouchDB on Windows - the gory details ==
+ There are 3 different ways of running CouchDB on windows.
+  * The simplest is the supplied couchdb.bat file in %COUCHDB%\bin. This launches couchdb.bat
using the supplied Win32 GUI werl.exe erlang Read/Eval/Print/Loop tool. You can change the
font/background/colour here (hint).
+  * If you modify the script, or set an environment variable "set erl=erl" prior to launching
the batch file, erlang will run with the command prompt version, erl.exe which is less intrusive
as a pure console application.
+  * Run CouchDB as a windows service. This allows CouchDB to run unattended, and will survive
logins, logouts, and reboots, however introduces some additional complexities if you wish
to debug or interact with CouchDB. The actual service is a wrapper program erlsrv.exe  which
acts as a restart and control shell. CouchDB starts up from erl.exe and the epmd.exe portmapper
is also launched.
+ The werl.exe version is clearly simplest for interactive and development usage, but the
service is far superior for production usage. Full information is available for [[|erlsrv.exe]]
and [[|erl.exe]] which also covers [[|werl.exe]];
refer to [[|couchdb.bat]]
for current flags passed to the emulator.
+  * use erl or werl with "-noinput" flag which provides a stdout only console - keep those
grubby fingers out. Users can still kill or ctrl-C out.
+  * use erl "-detached" flag to start up the erlang shell completely hidden from users. On
logout however, CouchDB will still be shut down, and users can still kill via process or task
manager tools.
+  * use [[|erlsrv.exe]] and [[|sc.exe]]
to set up various combinations of your CouchDB service in debug and normal modes. Start the
service in debug mode to interact with the console, then stop it & restart the normal
mode to simulate full production.
+ Assuming you have an environment variable %COUCH% already set then:
+ || use case || erlsrv parameters || impact ||
+ || deployed CouchDB service up to 1.0.2 inclusive || erlsrv.exe add "Apache CouchDB" -w
"%COUCH%\bin" -ar "-sasl errlog_type error -s couch" -c "Apache CouchDB 1.0.2" || service
will not restart automatically; VM not tuned ||
+ || Start CouchDB in debug mode || erlsrv.exe add "CouchDeBug" -workdir "%COUCH%\bin" -onfail
restart_always -debugtype console -args "-sasl errlog_type error -s couch +A 4 +W w" -comment
"CouchDeBug"|| service will restart automatically. Console is accessible to users logged into
winsta0 i.e. local interactive users for input ||
+ || Production mode ||erlsrv.exe add "CouchDB_Production" -workdir "%COUCH%\bin" -onfail
restart_always -args "-sasl errlog_type error -s couch +A 4 +W w" -comment "CouchDB_Production
1.0.2" || Console hidden, service restarts automatically ||

View raw message