hub.darcs.net :: simon -> darcsden -> files

darcsden is a "code forge" for [darcs] repositories, allowing one or
more darcs repos to be published and managed via web or ssh
interfaces, online or on your local machine. It provides several
executables:

- darcsden - the web application, for browsing and managing users, repos, issues
- darcsden-ssh - a simple ssh server supporting darcs push/pull
- darcsden-post-hook - a helper for updating issues from commit messages
- den - a command line tool for managing a local darcsden instance

darcsden can be configured for local single-user use, or as a shared multi-user server.
In single-user mode it stores all data on the filesystem.
In multi-user mode it uses CouchDB and redis databases, in addition to darcs repos on the filesystem.

http://hackage.haskell.org/package/darcsden
http://hub.darcs.net/simon/darcsden

[darcs]: https://darcs.net

## darcs hub

https://hub.darcs.net is a central community instance of darcsden,
operated by darcsden's maintainer. You can explore it and use it free
of charge. If it meets your needs, there's no need to install darcsden
yourself. Otherwise, read on.

## Installing

Currently, darcsden should be built with GHC 8.6 (GHC 8.0+ may also work).

Installing with [stack]:

    stack install

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

[stack]:           https://www.fpcomplete.com/haskell/get-started

Installing with [cabal]:

    cabal install -w ghc-8.6.5  # ghc-8.6.5 should be in $PATH

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

[cabal]:           https://www.haskell.org/cabal

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

### Installing on Windows

darcsden indirectly depends on some C libraries, which stack/cabal
will not install: OpenSSL, required by `darcsden-ssh`, and pcre,
required by `darcsden-post-hook`. On Windows, you probably don't need
either of those executables, so they should be disabled. For now, you
must do this manually by adding build flags to the install command:

    stack install --flag darcsden:-ssh flag darcsden:-posthook
    
or:

    cabal install -f-ssh -f-posthook

## Configuration

Darcsden can be configured via a "darcsden.conf" file in the startup
directory, or specified with the --config option:
    
    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

### Web assets

The web app expects darcsden's public/ directory to be accessible as
`./public`, so run `darcsden` from within the main source directory.
Or..

### Web server integration

If you run a web server in front of the darcsden web app, configure it
to serve /public/* requests from darcsden's public/ directory.

Some partial web server config examples.

Apache:

    <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:

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

## Multi-user setup

Extra configuration needed for running in multi-user mode:

### Databases

CouchDB (for storing user/repo/repository data) and Redis (for storing
web session data) should be running on their default ports. (Or, you
can change the ports in Settings.hs before building darcsden).
Initialise the databases by running:

    darcsden --install

### User account

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...

## Running

### Running in single-user mode

From the main darcsden source directory (with ./public/), run:

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

### Running in multi-user mode

The `darcsden` and `darcsden-ssh` servers should be run as the `darcsden` user.

For persistent operation, you could run them manually inside
persistent dtach or screen sessions:

    sudo -HE -u darcsden darcsden

and:

    sudo -HE -u darcsden darcsden-ssh

Or better, configure them as daemons, eg using systemd or supervisord.
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"

<!-- ### 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, relatively 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 is the current maintainer of darcsden, and operator of
darcs hub.

Recent contributors include Alp Mestanogullari, Jeffrey Chu, Ganesh
Sittampalam, BSRK Aditya (sponsored by Google's Summer of Code),
and Bertram Felgenhauer.

darcsden depends many fine FOSS projects and libraries, including
Darcs, Snap, GHC, Twitter Bootstrap, JQuery, and more.