The Pitch
Precursor is the best way to collaborate on early prototypes with your team. Start every project with a new Precursor doc, share the link with your team, hit the speaker in the lower right to share your audio, and start sketching out your ideas. It's better than Sketch, Skype, and Slack put together.
Check the How to doc to learn about some of Precursor's features.
This is the code that runs Precursor
The Precursor founders, Danny and Daniel, have generously made the Precursor code open to the public. Precursor is an excellent resource if you're interested in Clojure, ClojureScript, Datomic, advanced CSS, or just how to put together a modern web app.
Setting up your own instance
If you're a company that wants to run Precursor on your own hardware, please contact Daniel for help getting set up. We've made some effort to allow anyone to spin up their own Precursor instance, but there are still some roadblocks to work around.
Contributing
We're still working out requirements for this. There will likely be a contributor's agreement. Please follow @precursorapp for updates.
Development Requirements
Downloading jars
Some jars are hosted in a private s3 repository. You'll need the AWS secret key to download them. Unfortunately, AWS does not like it when their keys are exposed, so it has to be obfuscated here.
export
export PRCRSR_JARS_USERNAME=AKIAT7EJ2N4CR3WFDRFJ
export PRCRSR_JARS_PASSWORD=$(echo "zhLtbtGUnn7THm21k6mSNCUNg4ZxYUoqnp8NUd2h" | tr "[A-Za-z]" "[N-ZA-Mn-za-m]")
(if you don't have tr on your machine, the password is encrypted with rot13.
Frontend
Fetch our fork of Om, which is installed as a submodule (in yaks/om):
git submodule update --init
Install node dependencies (requires a recent version of node):
npm install
Compile the frontend clojurescript assets:
lein clean
lein figwheel dev
Database
Download Datomic Pro Starter Edition https://my.datomic.com/starter. You'll have to create a new account with Datomic to get a license key.
Unzip it Datomic and add your license key to config/samples/dev-transactor-template.properties
Start Datomic from within the datomic directory:
bin/transactor config/samples/dev-transactor-template.properties
Webserver
First, create a secrets file. Unfortunately we can't share the development secrets.
Copy pc.profile/ProfileSchema into a new file, resources/secrets/my-secrets-file.edn.
Replace the values, filling in the fields with proper values. This part is not well-tested. You can try putting dummy values for most things. Please open issues on GitHub if you run into problems. PRs to simplify this process are very welcome.
Then encrypt the file using gpg with a symmetrical passphrase:
gpg --armor --batch --symmetric --output my-secrets-file.edn.gpg my-secrets-file.edn
Enter your passphrase at the prompt (I've used "hello" as an example).
Start the webserver:
GPG_PASSPHRASE='hello' PROFILE_SOURCE='secrets/my-secrets-file.edn.gpg' lein run
Now you should have a server running on port 8080 and start an nrepl server on port 6005.
Go to http://localhost:8080. If you see the app, everything worked. If not, check the output of lein run for errors.
Project layout
Backend
Precursor's infrastructure is laid out in this doc https://precursor.precursorapp.com/document/Backend-Infrastructure-17592197950857
src/pc/init.clj is the entry point that sets up all of the server's state
src/pc/views/ contains HTML generated by the backend. This is where the blog, admin pages, and the bootstrap HTML for the frontend live.
src/pc/models/ contains the very light layer for fetching, creating, and updating Precursor's data abstractions. We decided to stay as close to the Datomic representation as possible, and this has worked very well for us. In general, Precursor's philosophy is to use abstractions sparingly because abstractions are hard. Bad abstractions are usually much worse than too few abstractions.
src/pc/http/ contains the code that handles web requests lives here, except for the code that actually sets up the http server, which lives at src/pc/server.clj.
src/pc/http/sente.clj is a poorly-named file (Precursor switched from Sente to Talaria) that handles realtime messages to the browser over websockets. Ideally, it would be split into multiple smaller files. You can see a better approach in src/pc/http/issues.clj.
There is more, but those are the main pieces.
Frontend
The frontend is very similar to CircleCI's open-source frontend. I'd recommend watching Brandon Bloom's Clojure/West talk Building CircleCI's Frontend with Om, for a quick overview.
src-cljs/frontend/core.cljs is the entry point.
src-cljs/frontend/components/ contains all of the view code.
src-cljs/frontend/controllers/ contains all of the code that changes state.
There is more, but those are the main pieces.
Notable libraries/software
Database is Datomic, we've been very happy with it in conjunction with Datascript. I can't imagine building Precursor's realtime features without it. Some of the more advanced features we had planned, like forking and infinite undo would be much harder without it.
HTTP server is Immutant. We have found it very stable. We switched from http-kit, which was also pretty good, but doesn't support features needed to implement back pressure.
We manage http connections with Talaria.
We use Figwheel to speed up development on the frontend.
Gumshoe helps us to iterate faster on the backend.
Troubleshooting
Try running:
lein clean