Getting started

Welcome to ShipClojure! This guide will help you get your development environment set up and running quickly.

Prerequisites

  1. Install mise for managing development environment tools

  2. Clone the ShipClojure repository and set up your own repository

    # Clone the repository
git clone git@github.com:shipclojure/shipclojure.git
cd shipclojure

# Set up for future updates
git remote rename origin upstream
git remote add origin <your_repository_git_address>

    See Getting Updates for more details on how to manage ShipClojure updates.

  3. Ensure you have docker installed on your computer for development

Getting started

  1. Install dependencies with mise. From project root run:
mise install

This will install all of the required dependencies for the project, such as babashka, correct clojure & java version and other quality of life tools.

Note: This step is also covered by launchpad (bb dev from the next step), but this ensures you have babashka installed.

  1. Start the dev environment through launchpad:
bb dev # use launchpad to setup everything for you

That's it 🎉! This will boot everything required for development and will start a REPL on port 7888. It includes the correct aliases so all you need now is to connect from your favorite editor and start working!

Under the hood: What get's started:

For people that are a bit alergic to blackbox magic, here's what bb dev does under the hood:

The launchpad config is in bin/launchpad. When we run this script, it does the following:

  • Checks and installs mise deps if not installed
  • Checks and installs npm deps if not installed
  • Starts the shadow-cljs builds for the main app and portfolio
  • Starts the dev docker containers for use in development
  • Ensures secrets are in the correct place (see secret management for more details.

After running docker compose command, you'll have access to the PostgreSQL Database available at localhost:5432 (username & password are in docker-compose.yml).

The app automatically connects to these containers. If you wish to use your own postgres connections, change the credentials from resources/.secrets.edn and reset the system.

Using the REPL

The CLJ REPL is open on 7888 and everything should already be running. Just connect to it you can start working.

If you want to connect to the ClojureScript REPL, it lives on port 7002.

Full details are in the REPL Workflow documentation.

Testing

To run the tests:

# Run all tests
bb test

# Alternative: Run all tests using bin/kaocha directly
bin/kaocha

Building for Production

To create a production build:

bb release

This will build optimized frontend assets and prepare the application for deployment.

Next Steps

ShipClojure Documentation
Previous
Table of contents
Next