Duct is a minimal framework for building web applications in Clojure, with a strong emphasis on simplicity.

Duct is experimental software and subject to future change. The current releases are primarily meant for testing and development purposes. Use at your own risk.

Create a new Duct project with Leiningen.

lein new duct <<your project name>>

Change directory into your new project.

cd <<your project name>>

Then check your new project's README.md file for instructions on setting up a development environment.

Duct consists of a Leiningen template and a small support library.

Duct depends on existing libraries for the majority of its functionality.

Externally, Duct follows the Twelve-Factor App methodology.

Internally, Duct uses Stuart Sierra's Reloaded Workflow.

Duct prefers local bindings over global state.

Duct separates configuration and environment.

Duct applications are divided by purpose, rather than layer.

Duct is designed to produce a standalone web application, configured with environment variables, and logging to STDOUT. Typically it will sit behind a proxy or load-balancer, and works well in environments like Heroku and Docker.

Internally, Duct projects are structured with the Component library. Components handle the lifecycle of the web server, and connections to other services and databases. It's highly recommended you avoid any global state, and even dynamic bindings are discouraged.

The routes of the application are divided into endpoints. These are functions that take a component map, and return a Ring handler function. Duct therefore relies on closures and lexical scoping to pass database connections and other configuration data to the routes.

Endpoints should resemble microservices, grouping routes by purpose. An endpoint might handle user authentication, or handle comments on a post. Strive to keep your endpoints small and focused.

Duct projects are structured as below. Files marked with a * are kept out of version control.

.
├── README.md
├── dev
│   ├── local.clj *
│   └── user.clj
├── profiles.clj *
├── project.clj
├── resources
│   ├── errors
│   ├── public
│   └── {{project}}
│       └── endpoint
│           └── {{endpoint}}
├── src
│   └── {{project}}
│       ├── component
│       ├── endpoint
│       │   └── {{endpoint}}.clj
│       ├── main.clj
│       └── system.clj
└── test
    └── {{project}}
        └── endpoint
            └── {{endpoint}}_test.clj

Copyright © 2014 James Reeves

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.