darcs repository web UI and hosting app. This is the main darcsden trunk, which also runs hub.darcs.net. (http://hub.darcs.net)

root / README.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
darcsden is a darcs repository hosting platform, providing a web
application for browsing and managing repos, users, and issues, and a SSH
server for push/pull and quick repository creation.

Home: http://hackage.haskell.org/package/darcsden

To install:
-----------

Installation should go something like this, please send corrections:

Using stack:

    # download stack, see http://haskell.org/downloads
    stack install hsx2hs
    stack install [--flag darcsden:cli] [--flag darcsden:ssh] [--flag darcsden:closing]

This will install the `darcsden` executable in `~/.local/bin` or the windows equivalent.

Using cabal:

    cabal install hsx2hs
    cabal install [-fcli] [-fssh] [-fclosing]

This will install executables in `~/.cabal/bin` or the windows equivalent.

The optional flags can also install:
- the `den` command-line tool which helps with local darcsden use
- the `darcsden-ssh` daemon which allows push/pull via SSH
- the `darcsden-post-hook` for automatically closing issues mentioned in commit messages.

Note, currently it is recommended to build darcsden-ssh with GHC 7.6
to avoid http://hub.darcs.net/ganesh/ssh/issue/3 . Eg:

    cabal configure -fssh -w ghc-7.6.3
    cabal build
    cp dist/build/darcsden-ssh/darcsden-ssh ...

In darcsden.cabal there are some more optional flags, which can assist with building on windows.

To run darcsden you also need:

- Redis   (for storing web session data)
- CouchDB (for storing user/repo/repository data)

Both should be running on their default port, or you can change that in
Settings.hs. You should configure them by running:

    darcsden --install

You should have a "darcsden" user account (for running the app and owning
the files), with a ssh key:

    adduser --system --home /home/darcsden --shell /bin/bash --group --gecos DarcsDen darcsden
    sudo -u darcsden ssh-keygen

To avoid obscure errors due to mixed file ownership in ~/.darcs/cache,
always run darcsden as the darcsden user, with $HOME set properly.
So if using sudo, include the -H flag, like this:

    sudo -Hu darcsden COMMAND...

The directory where you start the web app should contain darcsden's
public/ directory. Or you can run it behind a web server that'll serve
/public/* requests from that directory.


To configure:
-------------

Darcsden's can be configured via "darcsden.conf" from the current working
directory or by specifying the config file location via
    
    darcsden --config /path/to/darcsden.conf

The configuration file has the following format (includes all currently available options from the default settings). Note that you do not need to set all options, but only those that are different from the default configuration.
    
    # for logs and user repositories, also important for the ssh key locations
    homeDir = .
    # for serving the page (if not specified, this is automatically detected
    # from the cabal install destination)
    publicDir = ./public
    # log file locations
    accessLog = ./log/access.log
    errorLog = ./log/error.log
    
    # Enable user registration?
    multiuser = True
    # Enable optional issue trackers?
    issuetrackers = True
    # Delete repos from the filesystem when deleted in the web UI?
    deletefiles = True
    # Support darcs-1 repositories?
    supportdarcs1 = True
    
    # resource limits
	# granularity is 5s, precision is +/-5s
    maxRequestTime = 30
    maxFileDisplaySize = 200000
    maxPatchDisplaySize = 200000
    
    # Enable github integration, also needs githubAppIdVarName
    # and githubAppPwdVarName.
    githubOAuth = True
    
    # Enable Google integration, also needs googleAppIdVarName
    # and googleAppPwdVarName.
    googleOAuth = True
    
    # To configure github integration, register an application at github.
    # Store the client id and client secret as environment variables.
    githubAppIdVarName = GITHUB_CLIENT_ID
    githubAppPwdVarName = GITHUB_CLIENT_SECRET
    
    # To configure google integration, register an application at google.
    # Store the client id and client secret as environment variables.
    googleAppIdVarName = GOOGLE_CLIENT_ID
    googleAppPwdVarName = GOOGLE_CLIENT_SECRET
    
    # send address: you need to be able to send mails from
    # this address using the default sendmail executable
    sendName = darcdsden
    sendEmail = darcsden@localhost
    
    # this name/email is shown to users for contact information
    adminName = admin
    adminEmail = webmaster@localhost
    
    # canonical public url of the web app
    # this is important eg for loading stylesheets and js
    # it must end with a slash /
    baseUrl = http://localhost:8900/
    hostname = localhost
    # port on which the http server listens
    httpPort = 8900
    # port for ssh connections
    sshPort = 22
    
    # where the couchDB server is
    couchHost = 127.0.0.1
    # port of the couchDB server
    couchPort = 5984
    # where the redis server is
    redisHost = 127.0.0.1
    # port of the redis server
    redisPort = 6379

Some features require extra configuration to work:

- OAuth:

    - Create developer applications for the oauth services:
       - Github: https://github.com/settings/applications
       - Google: https://code.google.com/apis/console
    - Set callback urls:
       - Github: same as your baseUrl
       - Google: multiple callbacks:
           - baseUrl ++ "register/google/response"
           - baseUrl ++ "login/google/response"
           - baseUrl ++ "sync/google/response"
    - Enter Client ID and Client secret into environment variables:
       - Github: Add these lines to your shell startup
           export GITHUB_CLIENT_ID=your_client_id
           export GITHUB_CLIENT_SECRET=your_client_secret
       - Google: Add these lines to your shell startup
           export GOOGLE_CLIENT_ID=your_client_id
           export GOOGLE_CLIENT_SECRET=your_client_secret

- Forgot Password:
    - Configure your default sendmail to be able to send emails
    - Edit sendEmail, and sendName to the email address you can use

- Webdriver Tests:
    - Download and start selenium server from http://docs.seleniumhq.org/download/
    - run ./dist/build/darcsden-test/darcsden-test
    - If you wish to run oauth tests:
        - Configure oauth
        - Add a test google and github account by adding the appropriate
          environment variables:
            - export GOOGLE_USERNAME, GOOGLE_PASSWORD, GITHUB_USERNAME, GITHUB_PASSWORD.
        - run ./dist/build/darcsden-test/darcsden-test --oauth


To start:
---------

For a quick test, run:

    sudo -Hu darcsden darcsden

and visit http://localhost:8900 (or other url configured in Settings.hs)
in your web browser.

This package provides separate executables for the web and SSH servers,
`darcsden` and `darcsden-ssh` respectively. You could run them manually
while logged in as the `darcsden` user via screen or dtach. Or, configure them
as daemons. See `darcsden.god`, or these sample supervisord.conf entries:

    [program:darcsden]
    command=sudo -EHu darcsden /path/to/darcsden
    directory=/home/darcsden
    priority=3
    redirect_stderr=true
    autostart=true
    autorestart=true
    environment=LANG="en_US.UTF-8"

    [program:darcsden-ssh]
    command=sudo -EHu darcsden /path/to/darcsden-ssh
    directory=/home/darcsden
    priority=3
    redirect_stderr=true
    autostart=true
    autorestart=true
    environment=LANG="en_US.UTF-8"

Here are some web server config examples.

Apache vhost:

    <VirtualHost *:80>
    ServerName my.host.name
    RewriteEngine on
    ProxyPreserveHost On
    ProxyErrorOverride On
    RewriteRule ^/(.*) http://127.0.0.1:8900/$1 [P]
    </VirtualHost>

Nginx:

    server {
      listen 0.0.0.0:80;
      server_name my.host.name;

      location / {
        proxy_set_header Host $host;
        proxy_pass http://127.0.0.1:8900;
      }
    }

Lighttpd (requires enabling `mod_proxy`):

    $HTTP["host"] == "my.host.name" {
        proxy.server = (
            "" => (
                ( "host" => "127.0.0.1", "port" => "8900" )
            )
        )
    }

Windows:
--------

darcsden indirectly depends on two external libraries: OpenSSL and pcre.

The -f-ssh flag can be used to disable the ssh server and remove the
dependency on OpenSSL.

The -f-closing flag disables the ability for checkins to automatically
close issues, removing the dependency on pcre.

OpenSSL can be installed from http://slproweb.com/products/Win32OpenSSL.html -
download "Win32 OpenSSL v1.0.1e" or whatever similar version is current.
[At the time of writing, darcs doesn't work with 64 bit Windows, but
if this changes then a 64 bit version can be downloaded from the same location.]

Pick a directory to install it to, e.g. c:/OpenSSL-Win32 - and install HsOpenSSL
with
cabal install HsOpenSSL --extra-include-dirs="c:/OpenSSL-Win32/include" --extra-lib-dirs="c:/Win32OpenSSL"

Running as a Windows service:
-----------------------------

darcsden depends on having CouchDB and redis running, so it also
makes sense to install these as services, though it's not essential.

redis can be setup as a Windows service using
https://github.com/kcherenkov/redis-windows-service

The redis service name is redis-instance.

CouchDB comes as a service already.

The CouchDB service name is something like
"Apache CouchDB01cd861ad1dbd850", look for "CouchDB" in the output
of "sc query" to get the exact name.

To install darcsden as a Windows service given the above names for
the redis and CouchDB services, identify the path to darcsden.exe
and to the darcsden source tree. Then alter the following command
appropriately and run it all on one line:

sc create DarcsDen
   binPath= "c:\path\to\darcsden.exe --service"
   start= auto
   depend= redis-instance/"Apache CouchDB01cd861ad1dbd850"

To uninstall the service, use "sc delete DarcsDen".


Contributing:
-------------

darcsden is a small, clean codebase that is fun to hack on. Discussion
takes place on the #darcs IRC channel, and useful changes will quickly
be deployed at hub.darcs.net, providing a tight dogfooding/feedback
loop. Here's how to contribute a patch there:

1. register at hub.darcs.net
2. add your ssh key in settings so you can push
3. fork your own branch: http://hub.darcs.net/simon/darcsden , fork
4. copy to your machine: darcs get http://hub.darcs.net/yourname/darcsden
5. make changes, darcs record
6. push to hub: darcs push yourname@hub.darcs.net:darcsden --set-default
7. your change will appear at http://hub.darcs.net/simon/darcsden/patches
8. discuss on #darcs, or ping me (sm, simon@joyful.com) to merge it

Credits:
--------

Alex Suraci created darcsden. Simon Michael led this release, which
includes contributions from Alp Mestanogullari, Jeffrey Chu, Ganesh
Sittampalam, and BSRK Aditya (sponsored by Google's Summer of Code).
And last time I forgot to mention two 1.0 contributors: Bertram
Felgenhauer and Alex Suraci.

darcsden depends on Darcs, Snap, GHC, and other fine projects from the
Haskell ecosystem, as well as Twitter Bootstrap, JQuery, and many more.