How to Deploy Your Project to Clojars with Leiningen
So you've finished your Clojure project that you've worked so hard on and you're ready to show it off to the world. What's the next step? Pushing it to Clojars!
What is Clojars?
Clojars is a community maintained repository for open source Clojure libraries. It aims to make it dead simple to share and use Clojure libraries, and to encourage developers to make their projects available to use for automation tools like Leiningen.
Clojars repositories come in two flavors: Classic and Release. The Classic repository is a snapshot space in which anyone can deploy anything to it. The Release repository on the other hand, is a bit more strict and has a few requirements:
Projects cannot be snapshot versions.
Projects must have a :description, :license, and :url in their pom.xml or project.clj file.
Projects must be signed by the author's PGP key
NOTE: Clojars also supports the use of secure copy (SCP) and SSH keys for deployment; however, with the recent vulnerability in Bash Clojars has disabled the scp-based deploy services until further notice.
Let's Get Started
So now that we know what Clojars is, let's get started. There are a few basic dependencies that are required before we can deploy our projects.
Clojure
Leiningen (>= v2.1)
git (brew install git in Terminal)
gnupg (brew install gnupg && brew install gpg-agent)
After installing these dependencies, there are several steps we need to take to get things up and running.
GPG Agent and Creating Your GPG Key
GPG Agent is similar to ssh-agent in that it manages access to GPG keys that have been unlocked. The GPG agent must be running and can be started by typing gpg-agent --daemon in the Terminal.
Create your GPG key with the command gpg --gen-key. You will be prompted with a few options like key type, key size, and key expiration. You will also be asked for your real name, email address, comment, and a passphrase that will be asked of you each time you attempt to unlock your GPG key. Once everything is setup, you will receive something like this:
pub 2048R/8F4A321D 2014-10-28 uid Jayden Sung (clojarz) <[email protected]> sub 2048R/9A4REBA0 2014-10-28
The important bit is the first line after the forward slash, 8F4A321D. This value is the unique key ID that has just been generated. You will need to use this value when retrieving your GPG public key.
Set up SSH Key
Assuming you have GitHub setup on your machine, you should already have an SSH key. If you haven't generated an SSH key already, here's an excellent tutorial on how to do so.
Create a Clojars Account
Create an account here and fill out the basic information. Clojars requires that you give up your public SSH key and PGP key. In order to retrieve these keys and copy them onto your clipboard, type in
cat ~/.ssh/id_rsa.pub | pbcopy
and
gpg --export -a <YOUR-KEY-ID> | pbcopy
respectively. The keys will be placed on your clipboard, so make sure you paste the values into the registration form after executing each command.
How to Deploy
Now that the setup is done, it's time to deploy! Assuming you've used Leiningen to manage your project, you may need to configure your project.clj to include the required fields that were outlined earlier.
After that's squared away, all that's left to do is to run the command
lein deploy clojars
Here's an example of what to expect after running this:
» lein deploy clojars No credentials found for clojars See `lein help deploying` for how to configure credentials to avoid prompts. Username: jaydensung Password: Wrote /Users/jayden/Code/clojure_tictac/pom.xml Compiling clojure_tictac.core Created /Users/jayden/Code/clojure_tictac/target/clojure_tictac-0.1.0.jar You need a passphrase to unlock the secret key for user: "Jayden Sung (clojarz) <[email protected]>" 2048-bit RSA key, ID 8F4A261C, created 2014-10-28 Sending clojure_tictac/clojure_tictac/0.1.0/clojure_tictac-0.1.0.pom (3k) to https://clojars.org/repo/ Sending clojure_tictac/clojure_tictac/0.1.0/clojure_tictac-0.1.0.jar (101k) to https://clojars.org/repo/ Sending clojure_tictac/clojure_tictac/0.1.0/clojure_tictac-0.1.0.jar.asc (1k) to https://clojars.org/repo/ Sending clojure_tictac/clojure_tictac/0.1.0/clojure_tictac-0.1.0.pom.asc (1k) to https://clojars.org/repo/ Could not find metadata clojure_tictac:clojure_tictac/maven-metadata.xml in clojars (https://clojars.org/repo/) Sending clojure_tictac/clojure_tictac/maven-metadata.xml (1k) to https://clojars.org/repo/
If everything went well and you were presented with an output similar to the one above, then you're all set! Your project has been deployed to the Clojars Classic repository. To view your project, log into Clojars and you should see it on your Dashboard. Additionally, you can submit it into the Releases repository by going to your newly deployed project and clicking on the Promote button.