Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 215 lines (174 sloc) 9.039 kb
6428af7 @technomancy Add deploy guide.
authored
1 # Deploying Libraries
2
3 Getting your library into [Clojars](http://clojars.org) is fairly
4 straightforward as is documented near the end of
3b53949 @technomancy Remove mention of preview from docs; use stable branch.
authored
5 [the Leiningen tutorial](https://github.com/technomancy/leiningen/blob/stable/doc/TUTORIAL.md).
329b4b7 @technomancy Un-deprecate :auth profile since full-disk encryption is a good use case...
authored
6 However, deploying elsewhere is not always that straightforward.
0dfa867 @technomancy Clarify deployment guidelines in tutorial and deploy guide.
authored
7
6428af7 @technomancy Add deploy guide.
authored
8 ## Private Repositories
9
10 There may be times when you want to make a library available to your
11 team without making it public. This is best done by setting up a
50e14e0 @technomancy Document gpg key generation in deployment guide. Fixes #721.
authored
12 private repository. The simplest kind of private repository is a web
13 server pointed at a directory full of static files. You can use a
b5a193d @technomancy Switch :repositories to vector format to preserve ordering.
authored
14 `file:///` URL in your `:repositories` to deploy that way if the
50e14e0 @technomancy Document gpg key generation in deployment guide. Fixes #721.
authored
15 directory is local to the machine on which Leiningen is running.
16 [Amazon S3](http://aws.amazon.com/s3/) buckets are another simple
17 choice; you can deploy to S3 buckets using
18 [S3 wagon private](https://github.com/technomancy/s3-wagon-private).
a6659e1 @technomancy Documentation, news, todo updates.
authored
19
20 Alternatively you can run a private repository on your own server.
21 Both [Archiva](http://archiva.apache.org/) and
22 [Nexus](http://nexus.sonatype.org/) provide this as well as proxying
23 to other repositories, so you can set `:omit-default-repositories` in
24 project.clj, and dependency downloads will speed up by quite a bit
6428af7 @technomancy Add deploy guide.
authored
25 with only one server to check.
26
b99b57a @technomancy Clarify that :password and :passphrase are used by different repositorie...
authored
27 The private server will need to be added to the `:repositories`
6428af7 @technomancy Add deploy guide.
authored
28 listing in project.clj. Archiva and Nexus offer separate repositories
29 for snapshots and releases, so you'll want two entries for them:
30
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
31 ```clj
b5a193d @technomancy Switch :repositories to vector format to preserve ordering.
authored
32 :repositories [["snapshots" "http://blueant.com/archiva/snapshots"]
33 ["releases" "http://blueant.com/archiva/internal"]]
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
34 ```
6428af7 @technomancy Add deploy guide.
authored
35
bd6959c @cemerick Add support for :deploy-repositories slot for deployment-only repositori...
cemerick authored
36 If you are are deploying to a repository that is _only_ used for deployment
37 and never for dependency resolution, then it should be specified in a
38 `:deploy-repositories` slot instead of included in the more general-purpose
39 `:repositories` map; the former is checked by `lein deploy` before the latter.
17e4cbf @michalmarczyk Mention ((user-settings) :deploy-repositories) in DEPLOY.md
michalmarczyk authored
40 Deployment-only repositories useful across a number of locally developed
4050d44 @technomancy Update tutorial and deploy guide for HTTP deploy and credential storage.
authored
41 projects may also be specified in the `:user` profile in `~/.lein/profiles.clj`:
17e4cbf @michalmarczyk Mention ((user-settings) :deploy-repositories) in DEPLOY.md
michalmarczyk authored
42
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
43 ```clj
b5a193d @technomancy Switch :repositories to vector format to preserve ordering.
authored
44 {:user {:deploy-repositories [["internal" "http://blueant.com/archiva/internal"]]}}
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
45 ```
bd6959c @cemerick Add support for :deploy-repositories slot for deployment-only repositori...
cemerick authored
46
a6659e1 @technomancy Documentation, news, todo updates.
authored
47 ## Authentication
bd6959c @cemerick Add support for :deploy-repositories slot for deployment-only repositori...
cemerick authored
48
eaa6935 @technomancy Mention keychain for handling gpg passphrases. Fixes #615.
authored
49 Deploying and reading from private repositories needs authentication
50 credentials. Check your repository's documentation for details, but
a6659e1 @technomancy Documentation, news, todo updates.
authored
51 you'll usually need to provide a `:username` and `:password` or
eaa6935 @technomancy Mention keychain for handling gpg passphrases. Fixes #615.
authored
52 `:passphrase`. Leiningen will prompt you for a password if you haven't
53 set up credentials, but it's convenient to set it so you don't have to
54 re-enter it every time you want to deploy. You will need
437cf55 @tobias Move gpg setup notes from DEPLOY to GPG [fixes #1073]
tobias authored
55 [gpg](http://www.gnupg.org/) installed and a key pair configured. If
56 you need help with either of those, see the
57 [GPG guide](https://github.com/technomancy/leiningen/blob/stable/doc/GPG.md).
4050d44 @technomancy Update tutorial and deploy guide for HTTP deploy and credential storage.
authored
58
329b4b7 @technomancy Un-deprecate :auth profile since full-disk encryption is a good use case...
authored
59 ### GPG
60
102dcad @cemerick docs update for changes to resolution of repository credentials (gh-768)
cemerick authored
61 If you specify a `:creds :gpg` entry in one of your `:repositories` settings
62 maps, Leiningen will decrypt `~/.lein/credentials.clj.gpg` and use that to find
63 the proper credentials for the given repository.
a6659e1 @technomancy Documentation, news, todo updates.
authored
64
65 ```clj
b5a193d @technomancy Switch :repositories to vector format to preserve ordering.
authored
66 :repositories [["releases" {:url "http://blueant.com/archiva/internal"
102dcad @cemerick docs update for changes to resolution of repository credentials (gh-768)
cemerick authored
67 :creds :gpg}]]
a6659e1 @technomancy Documentation, news, todo updates.
authored
68 ```
69
4050d44 @technomancy Update tutorial and deploy guide for HTTP deploy and credential storage.
authored
70 First write your credentials map to `~/.lein/credentials.clj` like so:
6428af7 @technomancy Add deploy guide.
authored
71
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
72 ```clj
a6659e1 @technomancy Documentation, news, todo updates.
authored
73 {#"blueant" {:password "locative1"}
74 #"https://clojars.org/repo"
4050d44 @technomancy Update tutorial and deploy guide for HTTP deploy and credential storage.
authored
75 {:username "milgrim" :password "locative1"}
76 "s3p://s3-repo-bucket/releases"
a6659e1 @technomancy Documentation, news, todo updates.
authored
77 {:username "AKIAIN..." :passphrase "1TChrGK4s..."}}
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
78 ```
4050d44 @technomancy Update tutorial and deploy guide for HTTP deploy and credential storage.
authored
79 Then encrypt it with `gpg`:
80
81 $ gpg --default-recipient-self -e \
82 ~/.lein/credentials.clj > ~/.lein/credentials.clj.gpg
83
84 Remember to delete the plaintext `credentials.clj` once you've
f3a12fa @technomancy Mention bug in gpg that prevents gpg from prompting for passphrase.
authored
85 encrypted it. Due to a bug in `gpg` you currently need to use
86 `gpg-agent` and have already unlocked your key before Leiningen
87 launches, but with `gpg-agent` you only have to enter your passphrase
88 once per login.
6428af7 @technomancy Add deploy guide.
authored
89
329b4b7 @technomancy Un-deprecate :auth profile since full-disk encryption is a good use case...
authored
90 ### Full-disk Encryption
91
92 If you use full-disk encryption, it may be safe to store your
93 credentials without using GPG. In this case, you can create an `:auth`
94 profile containing a `:repository-auth` key mapping URL regexes to
95 credentials. Your `~/.lein/profiles.clj` file would look something
96 like this:
97
98 ```clj
99 {:user {...}
100 :auth {:repository-auth {#"blueant" {:username "milgrim"
101 :password "locative1"}}}}
102 ```
103
104 ### Credentials in the Environment
105
a6659e1 @technomancy Documentation, news, todo updates.
authored
106 Unattended builds can specify `:env` instead of `:gpg` in the
107 repository specification to have credentials looked up in the
108 environment. For example, specifying `:password :env` will cause
109 Leiningen to look up `(System/getenv "LEIN_PASSWORD")` for that value.
102dcad @cemerick docs update for changes to resolution of repository credentials (gh-768)
cemerick authored
110 You can control which environment variable is looked up for each value
111 by using a namespaced keyword, like so:
112
113 ```clj
114 :repositories [["releases" {:url "http://blueant.com/archiva/internal"
115 :username :env/archiva_username
116 :passphrase :env/archiva_passphrase}]]
117 ```
118
119 Finally, you can opt to load credentials from the environment _or_ GPG credentials
120 by using a vector of `:gpg` and `:env/*` values to define the priority of each:
121
122 ```clj
123 :repositories [["releases" {:url "http://blueant.com/archiva/internal"
124 :username [:gpg :env/archiva_username]
125 :passphrase [:gpg :env/archiva_passphrase]}]]
126 ```
127
128 In this example, both `:username` and `:password` will be looked up in
129 `~/.lein/credentials.clj.gpg` first, and only if a value is not available there will
130 the `ARCHIVA_*` env vars be checked. This allows you to avoid creating profiles
131 just to use different credential sources in e.g. a local development environment
132 vs. a centralized build environment.
a6659e1 @technomancy Documentation, news, todo updates.
authored
133
134 ## Deployment
bd6959c @cemerick Add support for :deploy-repositories slot for deployment-only repositori...
cemerick authored
135
6428af7 @technomancy Add deploy guide.
authored
136 Once you've set up a private repository and configured project.clj
137 appropriately, you can deploy to it:
138
4050d44 @technomancy Update tutorial and deploy guide for HTTP deploy and credential storage.
authored
139 $ lein deploy [repository-name]
6428af7 @technomancy Add deploy guide.
authored
140
8e0fe8e @cemerick add recipe for Maven Central deployment to DEPLOY.md
cemerick authored
141 If the project's current version is a `SNAPSHOT`, it will default to
4050d44 @technomancy Update tutorial and deploy guide for HTTP deploy and credential storage.
authored
142 deploying to the `snapshots` repository; otherwise it will default to
143 `releases`.
8e0fe8e @cemerick add recipe for Maven Central deployment to DEPLOY.md
cemerick authored
144
145 ## Deploying to Maven Central
146
147 Deploying your libraries and other artifacts to [Maven
148 Central](http://search.maven.org/) is often desirable. Most tools that
149 use the Maven repository format (including Leiningen, Gradle, sbt, and
150 Maven itself) include Maven Central or one of its mirrors as a default
151 repository for resolving project dependencies. So, deploying your
152 libraries to Maven Central offers the widest distribution, especially if
153 your users are likely to be in languages other than Clojure.
154
155 Thankfully, Leiningen can deploy your libraries to Maven Central, with
156 a few additional bits of configuration. All of the guidance about
157 deploying to private repositories laid out above applies; but, here's a
158 step-by-step recipe from start to finish:
159
160 1. Register an account and groupId on `oss.sonatype.org`; refer to
161 [this](https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide)
162 for details on how to get registered (you can ignore most of the info on
163 that page regarding configuring Maven and/or ant, since we'll not be
164 touching those tools). Note that all artifacts you deploy to OSS will
165 need to use the groupId(s) you choose, so your project coordinates
166 should be set up to match; e.g.:
167 ```clojure
168 (defproject your.group.id/projectname "x.y.z" ...)
169 ```
170
171 2. Add your credentials for `oss.sonatype.org` to your
172 `~/.lein/credentials.clj.gpg` file. Something like this will do:
173 ```clojure
174 {#"https://oss.sonatype.org/.*"
175 {:username "username" :password "password"}}
176 ```
177 Refer to the instructions earlier on this page for how to encrypt a
178 plain-text `credentials.clj` using GPG.
179
180 3. Add the OSS deployment repository endpoints to your project.clj, e.g.:
181 ```clojure
b5a193d @technomancy Switch :repositories to vector format to preserve ordering.
authored
182 :deploy-repositories [["releases" {:url "https://oss.sonatype.org/service/local/staging/deploy/maven2/"
183 :creds :gpg}
184 "snapshots" {:url "https://oss.sonatype.org/content/repositories/snapshots/"
185 :creds :gpg}]]
8e0fe8e @cemerick add recipe for Maven Central deployment to DEPLOY.md
cemerick authored
186 ```
187
188 4. Conform to OSS' requirements for uploaded artifacts' `pom.xml` files;
189 all you need to do is make sure the following slots are populated
190 properly in your `project.clj`:
191 ```clojure
192 :description
193 :url
194 :license
195 :scm
196 :pom-addition
197 ```
198 Examples of OSS-acceptable values for these entries can be seen in this
199 [`project.clj`
200 file](https://github.com/cemerick/piggieback/blob/master/project.clj).
201 Note that all of them should be appropriate for *your* project; blind
202 copy/paste is not appropriate here.
203
204 5. Run `lein deploy`. Leiningen will push all of the files it would
205 otherwise send to Clojars or your other private repository to the proper
206 OSS repository (either releases or snapshots depending on whether your
207 project's version number has `-SNAPSHOT` in it or not).
208
209 6. If you're deploying a release, log in to `oss.sonatype.org`, and
210 close and release/promote your staged repository. (This manual step
211 will eventually be automated through the use of a plugin.) The release
212 will show up in OSS' releases repository immediately, and sync to Maven
213 Central on the next cycle (~ 1-4 hours usually).
214
Something went wrong with that request. Please try again.