hub.darcs.net :: toastal -> 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 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.

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.

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