diff --git a/Makefile b/Makefile index 4c42b76..2aa6090 100644 --- a/Makefile +++ b/Makefile @@ -121,11 +121,11 @@ build-clean: ## Clean build assets or given directory # ------- Code Quality --------------- # pre-commit-check: format lint test ## Run format, lint and test targets -format: ## Run cljstyle to check the formatting of Clojure code +format: ## Run standard-clojure-style to check the formatting of Clojure code $(info --------- standard-clojure-style-js Runner ---------) $(FORMATTER_RUNNER) check . -format-fix: ## Run cljstyle and fix the formatting of Clojure code +format-fix: ## Run standard-clojure-style and fix the formatting of Clojure code $(info --------- standard-clojure-style-js Runner ---------) $(FORMATTER_RUNNER) fix . diff --git a/README.md b/README.md index 552b1a3..8751cc5 100644 --- a/README.md +++ b/README.md @@ -11,62 +11,21 @@ [Parts](https://parts.ifs.tools) is a toolkit for therapists working with the [Internal Family Systems model](https://en.wikipedia.org/wiki/Internal_Family_Systems_Model). It provides a tool for easy, collaborative parts mapping, which can be used to facilitate conversations with clients during sessions. -## Run the service - -Run the service (clojure.main) - -```shell -clojure -M:run/app -``` - -Run the greet function (clojure.exec), optionally passing a `:name` key and value as arguments - -```shell -clojure -X:run/greet :team-name '"team name"' -``` - ## Development -Practicalli workflow overview: - -- start a REPL process in a Terminal -- open the project in a Clojure Editor and connected to the REPL -- write code and evaluate expressions in the editor using the source code files - -[Practicalli Clojure CLI Config](https://practical.li/clojure/clojure-cli/practicalli-config/) should be used with this project to support all aliases used. - -This project uses `make` tasks to run the Clojure tests, kaocha test runner and package the service into an uberjar. The `Makefile` uses `clojure` commands and arguments which can be used directly if not using `make`. - -`make` command in a terminal will list all the tasks available - -```shell -make -``` - - ### Run Clojure REPL -Start the REPL with the [Practicalli REPL Reloaded](https://practical.li/clojure/clojure-cli/repl-reloaded/) aliases to include the custom `user` namespace (`dev/user.clj`) which provides additional tools for development (Portal data inspector, hotload libraries, namespace reload) - ```shell make repl ``` -The local nREPL server port will be printed, along with a help menu showing the REPL Reloaded tools available. - -Evaluate the tools.ifs.parts namespace and a mulog publisher will start, sending pretty printed events to the console. Evaluate `(mulog-publisher)` to stop the mulog publisher. - -Call the `-main` function with or without an argument, or call the `greet` function directly passing an optional key and value pair. +This will start a Clojure REPL that includes shadow-cljs (which we use to build our frontend). When we connect to this from CIDER (with `cider-connect-clj`), the `dev/repl` namespace will be automatically loaded. -`(namespace/refresh)` will reload any changed namespaces in the Clojure project. - - -### Clojure Editor - -If a REPL has been run from a terminal, use the editor **connect*- feature. - -Otherwise, use the `:dev/reloaded` alias from Practicalli Clojure CLI Config to starting a REPL process from within a Clojure editor. +From that namespace: +- The app server can be (re)started with `(go)`. This will also start the `shadow-cljs` process for building the frontend and watching for changes. +- We can swtich to the ClojureScript REPL with `(cljs-repl)` +- Use `:cljs/quit` to return to the Clojure REPL ### Unit tests @@ -80,56 +39,31 @@ make test `make test-watch` will run tests on file save, stopping the current test run on the first failing test. Tests will continue to be watched until `Ctrl-c` is pressed. -## Format Code - -Check the code format before pushing commits to a shared repository, using cljstyle to check the Clojure format, MegaLinter to check format of all other files and kaocha test runner to test the Clojure code. - -Before running the `pre-commit-check` - -- [install cljstyle](https://github.com/greglook/cljstyle/releases){target=_blank} -- MegaLinter runs in a Docker container, so ensure Docker is running - -```shell -make pre-commit-check -``` - -Run cljstyle only - -- `make format-check` runs cljstyle and and prints a report if there are errors -- `make format-fix` updates all files if there are errors (check the changes made via `git diff`) - -Run MegaLinter only - -- `make lint` runs all configured linters in `.github/config/megalinter.yaml` -- `make lint-fix` as above and applies fixes +## Deployment -Run Kaocha test runner only +We use Kamal to deploy a Docker container that will run the uberjar built with `make dist`. -- `make test` runs all unit tests in the project, stopping at first failing test -- `make test-watch` detect file changes and run all unit tests in the project, stopping at first failing test +Make sure that the `KAMAL_REGISTRY_PASSWORD` env var is exported so that the deploy can work. +Also edit config/deploy.yml to ensure it matches your setup. See the [Kamal docs](https://kamal-deploy.org/docs/installation/). -## Deployment +### Build and test locally -Build an uberjar to deploy the service as a jar file +It’s possible to build an uberjar and run it locally to test before deploying: ```shell -make build-uberjar +make dist +java -jar target/parts-standalone.jar ``` -- `make build-config` displays the tools.build configuration -- `make build-clean` deletes the build assets (`target` directory) +### Deploy + +A deployment can be started via: ```shell -make docker-build +make deploy ``` -- `make docker-down` shuts down all services started with `docker-build` -- `make docker-build-clean` - -Or build and run the service via the multi-stage `Dockerfile` configuration as part of a CI workflow. - - ## License Copyright © 2024 Gosha Tcherednitchenko / A Possible Space Ltd