Dear wiki user,

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

The page "Quirks_on_Windows" has been deleted by JoanTouzet:

Fully migrated to the glazier repo

- <<Include(EditTheWiki)>>
- Using CouchDB does not require installing cygwin, or becoming a command-line 
guru. If you get stuck here your best bet is 
[[irc://|IRC on #couchdb]] or the mailing lists. This 
page will help you relax on Windows just as much as anywhere else!
- <<TableOfContents(2)>>
- == Quick Start ==
- So you just can't wait to relax can you? The fastest route is to:
-  * unzip [[|curl]] 
and add to your path
-  * install the corresponding 
[[|win32 OpenSSL]] binaries 
to your system path
-  * run the latest [[|couchapp 
-  * sign yourself up for free [[|iriscouch 
hosting]] or [[!/solutions/cloud|Cloudant hosting]] to 
get your own cloud-based couch ready to go - no need to install your own!
-  * read the [[|quick 
start notes]] on using [[|CouchApp]]
-  * wade into [[|the Definitive Guide]]
- If you wish, you can install CouchDB yourself instead of using a hosted 
option, using [[]].
- == 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 {{{%COUCHDB%\var\lib\couchdb\}}}
-  * log file is in {{{%COUCHDB%\var\log\couchdb\couch.log}}}
-  * 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 loss
-  * 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
-  * you can restart the CouchDB service via commandline, the Services control 
panel, or build yourself a shortcut or .cmd file to do the trick also:
- {{{
- net.exe stop "Apache CouchDB" && net.exe start "Apache CouchDB"
- }}}
-  * cURL works just fine on Windows -- once you understand the 
[[|unwritten rules of 
quoting]] 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 -H "Content-Type: application/json" -X PUT 
-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 -H "Content-Type: application/json" -X PUT 
-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 -H "Content-Type: application/json" -X PUT 
-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 community-provided 
[[|scripts]] helping you build from source if 
-  * use only 32-bit components even if you are building on a 64-bit 
-  * 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 browser or timing differences. They should pass on 
a re-run however
- == Upgrade ==
-  * recommendation is to backup, uninstall, re-install, validate using Futon 
test suite, restore data, rather than an in-place upgrade
-  * this ensures you have a cruft-free experience while both CouchDB, the 
windows build & its installer continues to change rapidly
-  * In practice the uninstaller will not delete your data!
- == 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 
-  * 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}}} or 
{{{HKLM/Software/WOW6432Node/Ericcson}}} on 64-bit Windows, and updating the 2 
ini files {{{%COUCHDB%\bin\erl.ini}}} and {{{%COUCHDB%\erts-*\bin\erl.ini}}} 
respectively. Erlang and therefore 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\}}} and {{{%COUCHDB%\var\run\couchdb\}}} as 
-  * you can optionally include a CouchDB database file simply by leaving it in 
- === 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.
-  * if you wish to enable the firewall port, add {{{netsh advfirewall firewall 
add rule name="Apache CouchDB" dir=in action=allow service=any enable=yes 
profile=any localport=5984 protocol=tcp}}}
- === 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 script {{{%COUCHDB%\bin\couchdb.bat}}}. 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 
-  * 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, but 
doesn't support copy/paste as easily.
-  * 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 
 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 
 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.1.1"}}} || 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 and CouchDB versions > 1.0.2 ||{{{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.1.1"}}} || 
Console hidden, service restarts automatically ||

Reply via email to