Skip to content
Newer
Older
100644 155 lines (106 sloc) 5.11 KB
afd7f57 @ato Added a sorely-needed README.
ato authored
1 Clojars web interface
2 =====================
3
4 This is the source code for the [Clojars](http://clojars.org/) jar
81d8034 @ato Fixup paragraphs.
ato authored
5 repository webapp.
afd7f57 @ato Added a sorely-needed README.
ato authored
6
81d8034 @ato Fixup paragraphs.
ato authored
7 If you're looking for user documentation, try
32d1b3d @cldwalker fix link to clojars-maintainers
cldwalker authored
8 the [wiki](http://github.com/ato/clojars-web/wiki/_pages). There is a
81d8034 @ato Fixup paragraphs.
ato authored
9 also a [FAQ](https://github.com/ato/clojars-web/wiki/About).
36a6c2d @ato Add contributing and license sections to README.
ato authored
10
3465560 @ato Use an absolute link to NEWS.md. #70
ato authored
11 See [NEWS.md](https://github.com/ato/clojars-web/blob/master/NEWS.md) for recent user-facing changes.
5c73e3e @ato Link to NEWS.md #70
ato authored
12
36a6c2d @ato Add contributing and license sections to README.
ato authored
13 Contributing
14 ------------
15
32d1b3d @cldwalker fix link to clojars-maintainers
cldwalker authored
16 Please report bugs or problems with the repository on the
17 [bug tracker](https://github.com/ato/clojars-web/issues).
36a6c2d @ato Add contributing and license sections to README.
ato authored
18
32d1b3d @cldwalker fix link to clojars-maintainers
cldwalker authored
19 Design discussions occur on the
20 [clojars-maintainers list](http://groups.google.com/group/clojars-maintainers)
36a6c2d @ato Add contributing and license sections to README.
ato authored
21 and the #leiningen channel on irc.freenode.org.
22
23 If you'd like contribute a change please send a GitHub pull request
32d1b3d @cldwalker fix link to clojars-maintainers
cldwalker authored
24 for a topic branch. Feel free to open a pull request early with a
36a6c2d @ato Add contributing and license sections to README.
ato authored
25 "not ready for merging" note or ask on the mailing list or IRC to get
26 feedback from other contributors.
27
32d1b3d @cldwalker fix link to clojars-maintainers
cldwalker authored
28 We try to make releases fairly soon after merging contributions,
36a6c2d @ato Add contributing and license sections to README.
ato authored
29 but post to the mailing list if it's been a week or two and you'd like
30 something pushed to the production website.
afd7f57 @ato Added a sorely-needed README.
ato authored
31
32 Running the webapp
33 ------------------
34
298904b @pupeno Run Clojars in auto-reload mode from the console and document it.
pupeno authored
35 There are several ways to run Clojars depending on what you intend to do with
36 it. Regardless of how you run it, you first need to do some setup:
afd7f57 @ato Added a sorely-needed README.
ato authored
37
298904b @pupeno Run Clojars in auto-reload mode from the console and document it.
pupeno authored
38 1. Install [Leiningen](http://github.com/technomancy/leiningen)
253d435 @ato Rework configuration: proper command-line switches and Heroku-style e…
ato authored
39 * Mac OS X Homebrew: `brew install leiningen`
298904b @pupeno Run Clojars in auto-reload mode from the console and document it.
pupeno authored
40
41 2. Install [SQLite3](http://www.sqlite.org/)
42 * Debian: `apt-get install sqlite3`
43 * Mac OS X Homebrew: `brew install sqlite`
afd7f57 @ato Added a sorely-needed README.
ato authored
44
a4287a7 @technomancy Add clojars.db.migrate namespace.
technomancy authored
45 3. Run the DB migrations: `lein run -m clojars.db.migrate`
afd7f57 @ato Added a sorely-needed README.
ato authored
46
253d435 @ato Rework configuration: proper command-line switches and Heroku-style e…
ato authored
47 To run the application using Leinigen 2:
298904b @pupeno Run Clojars in auto-reload mode from the console and document it.
pupeno authored
48
253d435 @ato Rework configuration: proper command-line switches and Heroku-style e…
ato authored
49 1. Run the webapp: `lein run` (see `--help` for options)
50
51 2. Now try hitting [localhost:8080](http://localhost:8080) in your web browser.
298904b @pupeno Run Clojars in auto-reload mode from the console and document it.
pupeno authored
52
253d435 @ato Rework configuration: proper command-line switches and Heroku-style e…
ato authored
53 To build a standalone jar for deploying to a server:
54
55 1. Compile with: `lein uberjar`
298904b @pupeno Run Clojars in auto-reload mode from the console and document it.
pupeno authored
56
253d435 @ato Rework configuration: proper command-line switches and Heroku-style e…
ato authored
57 2. Run the webapp: `java -jar target/clojars-web-*-standalone.jar`
afd7f57 @ato Added a sorely-needed README.
ato authored
58
298904b @pupeno Run Clojars in auto-reload mode from the console and document it.
pupeno authored
59 To run the application in auto-reload mode, from the console:
60
61 1. Run `lein ring server`
62
63 and that's it, it should automatically open a browser in [localhost:3000](http://localhost:3000).
afd7f57 @ato Added a sorely-needed README.
ato authored
64
65 If you'd like to run it out of an editor/IDE environment you can
66 probably eval a call to the `-main` function in
253d435 @ato Rework configuration: proper command-line switches and Heroku-style e…
ato authored
67 `src/clojars/main.clj`.
afd7f57 @ato Added a sorely-needed README.
ato authored
68
253d435 @ato Rework configuration: proper command-line switches and Heroku-style e…
ato authored
69 Configuration
70 -------------
71
72 All options are available as command-line switches. Additionally some
73 can be set using environment variables. See `lein run -h` for the
74 full list.
75
76 Options may be read from a file using the `-f` switch, setting the
77 `CONFIG_FILE` environment variable or by putting a file named
78 `config.clj` on the classpath. The config file should be a bare
79 Clojure map:
80
81 {:db {:classname "org.sqlite.JDBC"
82 :subprotocol "sqlite"
83 :subname "data/dev_db"}
84 :key-file "data/dev_authorized_keys"
85 :repo "data/dev_repo"
86 :bcrypt-work-factor 12
87 :mail {:hostname "localhost"
88 :from "noreply@clojars.org"
89 :ssl false}}
90
91 The classpath option can be used with Leiningen 2 profiles. When
92 running out of a source checkout using `lein run` the configuration
93 will be read from `dev-resources/config.clj`. When running automated
94 tests with `lein test` then `test-resources/config.clj` is used.
298904b @pupeno Run Clojars in auto-reload mode from the console and document it.
pupeno authored
95
7e608e0 add basic instructions to run the test suite
Gabriel Horner and Lake Denman authored
96
afd7f57 @ato Added a sorely-needed README.
ato authored
97 Test data
98 ---------
99
100 If you'd like to hack on the UI or search it might be useful to have
101 production-like metadata. I've put up a production database dump
102 (with password hashes and email addresses stripped of course) which
103 you can use like this:
7e608e0 add basic instructions to run the test suite
Gabriel Horner and Lake Denman authored
104
afd7f57 @ato Added a sorely-needed README.
ato authored
105 wget http://meshy.org/~ato/clojars-test-data.sql.gz
07eb86b @ato Update test data to use data/dev_db in README
ato authored
106 mkdir -p data
107 rm -f data/dev_db
108 gunzip -c clojars-test-data.sql.gz | sqlite3 data/dev_db
afd7f57 @ato Added a sorely-needed README.
ato authored
109
110 If you want all the actual jar files as well you can grab them via
111 [rsync](http://github.com/ato/clojars-web/wiki/Data).
112
113 SSH integration
114 ---------------
115
116 The SSH integration is kind of a hack and needs improvement.
117 Currently it uses [Nailgun](http://martiansoftware.com/nailgun/) but
118 the current setup has threading problems due to the way it does IO.
119
120 Basically `clojars.scp` implements the [SCP protocol](http://blogs.sun.com/janp/entry/how_the_scp_protocol_works)
121 and acts as a Nailgun "nail" so it can be called from the
122 command-line. Clojars writes an SSH `authorized_keys` file
123 with a line for each user's public key setting the login command to
124 `ng --nailgun-port 8700 clojars.scp USERNAME`.
125
126 To set it up:
127
128 1. Install the Nailgun `ng` C program. Just unpack the Nailgun source
129 and run `make` then copy the `ng` executable somewhere like `/usr/local/bin`
130
131 2. Create a "clojars" unix account with a disabled password.
132
133 3. Disable password authentication for that user by adding this to
134 `/etc/ssh/sshd_config`:
135
3115681 @ato Fix formatting of SSH instructions in README.
ato authored
136 Match User clojars
137 PasswordAuthentication no
afd7f57 @ato Added a sorely-needed README.
ato authored
138
253d435 @ato Rework configuration: proper command-line switches and Heroku-style e…
ato authored
139 4. Symlink in the authorized_keys file the webapp generates:
afd7f57 @ato Added a sorely-needed README.
ato authored
140
3115681 @ato Fix formatting of SSH instructions in README.
ato authored
141 cd /home/clojars
142 mkdir .ssh
143 cd .ssh
28b37a8 @ato Rename auth_keys to authorized_keys as SSH expects it to reduce confu…
ato authored
144 ln -s ...../clojars-web/data/authorized_keys authorized_keys
afd7f57 @ato Added a sorely-needed README.
ato authored
145
253d435 @ato Rework configuration: proper command-line switches and Heroku-style e…
ato authored
146 5. When running the webapp enable the nailgun server: `--nailgun-port 8700`
147
afd7f57 @ato Added a sorely-needed README.
ato authored
148
36a6c2d @ato Add contributing and license sections to README.
ato authored
149 License
150 -------
81d8034 @ato Fixup paragraphs.
ato authored
151
36a6c2d @ato Add contributing and license sections to README.
ato authored
152 Copyright © 2009-2012 Alex Osborne, Phil Hagelberg, Nelson Morris and [contributors](https://github.com/ato/clojars-web/graphs/contributors).
81d8034 @ato Fixup paragraphs.
ato authored
153
32d1b3d @cldwalker fix link to clojars-maintainers
cldwalker authored
154 Distributed under the Eclipse Public License, the same as Clojure. See the file COPYING.
Something went wrong with that request. Please try again.