Skip to content

Latest commit

 

History

History
228 lines (138 loc) · 7.07 KB

getting-up-and-running-in-development.md

File metadata and controls

228 lines (138 loc) · 7.07 KB

Getting Started

The following steps should get Braid running on your computer, ready for development.

If you're interested in getting Braid running in production, read: Deploying Braid

0. Prep

Before running Braid, you'll need to have Java, Leiningen, and Clojure CLI tools installed.

  1. Check if you have java installed by running java -version from your commandline. It should be at least version 1.8.0. If not, install openjdk or Oracle Java (the exact procedure depends on your OS, see Google).

  2. Check if you have leiningen installed by running lein --help from your commandline. If it's not installed, see the Leiningen website for instructions.

  3. Check if you have Clojure CLI Tools installed by running clj -h from your commandline. If they are not installed, see the Clojure website for instructions.

  4. Clone the braid repo (you may want to change the URL to your fork):

git clone [email protected]:braidchat/braid.git
  1. Go into the project directory:
cd braid

1. Braid REPL & Servers

From the project directory...

  1. Run the REPL:
lein repl

The repl starts you off in braid.dev.core, which is a dev-only namespace with some utility functions. The source is in: dev-src/braid/dev/core.clj

The main app entry point is braid.core with source under: src/braid/core.clj

  1. Inside the REPL, start the Braid system:
(start! 5555)

This will start all the various Braid components, including 3 web servers:

Server Port Description
desktop web client 5555 HTML, JS, CSS assets for desktop web client
api 5556 HTTP and Websocket API, communicates w/ db, etc.
figwheel 3559 cljs->js compiler and live-code reloader, do not visit directly
  1. Seed some data:
(seed!)

...and you're good!

Open http://localhost:5555 in your browser:

open http://localhost:5555

Login with:

username: [email protected]

password: foofoofoo

You should see a few messages and be able to reply.

In a private window, you can login as another user:

username: [email protected]

password: barbarbar

If you edit a .cljs file in the repo, it should auto-update the page in the browser (no need for refreshing). Note: when developing, you should always have the Chrome/Firefox inspector, with "Disable Cache" on (under the Network Tab).

Datomic

By default, Braid uses Datomic's in-memory database, which requires no set-up, but, it requires re-seeding every time you restart the REPL.

To have data survive a REPL restart, you'll need to persist it to disk by installing Datomic.

To install "Datomic Free":

  1. Download Datomic Free 0.9.5201 from https://my.datomic.com/downloads/free

  2. Unzip the download

To run Datomic:

  1. In a terminal session, cd into the directory and run the transactor:
cd ~/path/to/datomic-free-0.9.5201
bin/transactor config/samples/free-transactor-template.properties

You will need to keep this process running during development. You can kill the process when you're not using it and restart it using the command above.

In your Braid project, you'll need to create a profiles.clj with the following (and restart the REPL to pick up the changes).

;; deprecated method
{:user {:env {:db-url "datomic:free://localhost:4334/braid"}}
;; OR
;; new method, requires you to start the repl like `lein with-profile +braid repl`
;; instead of just `lein repl`
{:braid {:env {:db-url "datomic:free://localhost:4334/braid"}}

In production, we recommend "Datomic Starter" instead (instructions here).

Extras

Using Emacs + CIDER instead of terminals

Emacs users who wish to have their repl sessions integrated with their development environment should follow these steps.

First, install CIDER. Braid has the nREPL middleware CIDER depends on available under the cider profile in project.clj. To use this profile in Emacs, you'll need to edit the cider-lein-parameters variable. There are two ways to do this:

  • M-x set-variable cider-lein-parameters
  • C-h v cider-lein-parameters and then click or hit enter on "customize" and set it there

In either case, set the value of the variable to be with-profiles +cider repl :headless

This should be sufficient to run a Clojure repl for server-side development. To also integrate a ClojureScript repl for client-side development, follow the instructions from the Figwheel wiki here. Specifically, you'll need to add the following to your emacs config:

;; ~/.emacs.el or ~/.emacs.d/init.el

;; somewhere after calling (require 'cider)
(setq cider-cljs-lein-repl
      "(do (require 'figwheel-sidecar.repl-api)
           (figwheel-sidecar.repl-api/start-figwheel!)
           (figwheel-sidecar.repl-api/cljs-repl))")

With that, you should be able to just run M-x cider-jack-in-clojurescript and emacs will launch both a Clojure and a ClojureScript repl configured for Braid development.

Running Tests

Server Tests

lein test

Or, if you have quickie:

lein with-profile test quickie "chat.*"

Client Tests

Install PhantomJS and ensure that the phantomjs binary is available from your path. Once installed, you can run:

lein cljsbuild test once

to run the client-side tests once. If you prefer to have tests run automatically as you make changes, then run

lein cljsbuild test auto

Permgen issues?

If you're experience the error: java.lang.OutOfMemoryError: PermGen space, try the following:

  1. Add the following to project.clj or profiles.clj:
:jvm-opts ["-XX:MaxPermSize=128m" "-XX:+UseConcMarkSweepGC" "-XX:+CMSClassUnloadingEnabled"]`

  1. If you have lots of plugins in your lein :user profile (~/.lein/profiles.clj), remove some

  2. Switch to Java 1.8

Environment Variables

Various configuration options can be set via environment variables. Braid uses Environ to read environment variables.

An easy way to set variables during development is to create a profiles.clj file.

See ../profiles.sample.clj for sample profile options and instructions.

Getting Started w/ Clojure

If you don't have Leiningen installed, then:

On Mac:

  1. Install Homebrew by following the instructions at: http://brew.sh/
  2. Use Homebrew to install Leiningen:
brew install leiningen

For other platforms, see: https://github.com/technomancy/leiningen/wiki/Packaging