v1.8.0

[jacobobryant]

See the announcement post for commentary.

Changes

• Use Aero to parse config.
• Switch from bb tasks to plain clj-based tasks.
• When using :db.op/upsert on a document that doesn't yet exist, use the provided :xt/id value if there is one instead of always using (random-uuid) as the value.
• Make use-xtdb get the value of :biff.xtdb.jdbc/jdbcUrl from the :biff/secret function if it's defined as a secret.
• Documentation fixes/improvements.
• Make server-setup.sh delete Trenchman artifacts after installing.
• Add libs to forward Java logs to slf4j.
• Update cider-nrepl to 0.45.0

Thank you to @mathisto, @carlos, @olavfosse, and @wunki for contributions.

Upgrade instructions

• Check the upgrade instructions for any previous releases, in case there are optional upgrades you'd like to apply.
• Update your Biff dependencies (in deps.edn, bb/deps.edn and/or tasks/deps.edn) to :git/tag "v1.8.0", :git/sha "3b2fa14"

Optional: upgrade config to use Aero

Apply the changes in this commit to your project:

1. Copy the new resources/config.edn file into your project. (NOTE: this new file should be saved at resources/config.edn, not config.edn).
2. Copy the new resources/config.template.env file into your project. Copy it to both resources/config.template.env and config.env.
3. Add /config.env to your .gitignore file.
4. Edit resources/config.edn and config.env to include any custom config that you previously put in config.edn or secrets.env. For example, you'll need to copy the values of COOKIE_SECRET and JWT_SECRET from secrets.env into config.env. resources/config.edn will be parsed with Aero. To specify different config values for different environments, you'll do e.g. {:example/foo #profile {:prod "bar" :dev "baz"} ... instead of {:prod {:example/foo "bar" ...} :dev {:example/foo "baz" ...} .... Here's some more migration advice.
5. Test your config. Add the check-config function to your repl.clj file. Then run bb dev and evaluate (check-config) from your editor. (You can also do (biff/pprint (check-config)) if needed.) Make sure everything looks correct.
6. Run git add .; git commit.
7. If your app is already deployed, run bb deploy and then bb prod-repl. Evaluate (check-config) again to make sure the new config is available in production.
8. Edit your main namespace and replace biff/use-config and biff/use-secrets with biff/use-aero-config. Run bb dev and make sure everything works locally. Then make a new commit, run bb deploy, and ensure everything works in production.

NOTE: this will make your application use the new Aero config, however, bb tasks will still read from the old config.edn file. To completely upgrade, you'll need to switch to clj tasks.

Optional: switch from bb tasks to clj tasks

If you switch to clj tasks, you must first upgrade your config to use Aero as described above.

Apply the changes in this commit to your project:

1. Add the :dev and :prod aliases to your deps.edn file. Replace :local/root "../libs/tasks" with :git/url "https://github.com/jacobobryant/biff", :git/tag "v1.8.0", :git/sha "3b2fa14", :deps/root "libs/tasks" and change com.example to your main namespace.
2. Add the dev/tasks.clj file to your project.
3. Edit your -main and start functions like so.
4. If you set up a server with server-setup.sh, SSH into it as root, edit /etc/systemd/system/app.service, and change the ExecStart line to ExecStart=/bin/sh -c "mkdir -p target/resources; clj -M:prod". Then run systemctl daemon-reload. Also make the same change in your server-setup.sh file. (Note: new projects also have server-setup.sh set BIFF_PROFILE=prod instead of BIFF_ENV=dev, but BIFF_ENV is still recognized.)
5. Run clj -M:dev dev to make sure everything works locally, then (if you did step 4) run clj -M:dev deploy and make sure it works in prod.
6. Recommended: add alias biff='clj -M:dev' to your .bashrc file.

Run clj -M:dev --help (or biff --help if you set up the alias) for a list of available commands. e.g. instead of running bb dev and bb deploy, you'll now run clj -M:dev dev and clj -M:dev deploy.

Optional: make your app work with Docker/Uberjars

After you upgrade to clj tasks, you can run clj -M:dev uberjar to generate an Uberjar for your app. You can also add this Dockerfile to your app. The recommended way for most people to deploy Biff is still the old way (setting up a DigitalOcean droplet with server-setup.sh and deploying with clj -M:dev deploy). But for those who know they want to deploy another way, clj -M:dev uberjar and the Dockerfile are provided as a convenience.

You'll need to make a few additional changes to your project. See this commit:

• Add (:gen-class) to your main namespace.
• Update css-path and js-path so they don't break when called inside an Uberjar.
• Add .dockerignore to your project.

Optional: clean up

If you followed the instructions above, there will be several files and directories that you no longer need. Feel free to delete them:

• bb.edn
• bb/ (previously this folder was named tasks/)
• config.edn and secrets.env (these aren't checked into git by default, so be sure you've migrated all your config over to the new files before you delete them)

Additionally, you can move your repl.clj file into the new dev directory and your test.clj file into a new test directory. You'll also need to edit deps.edn and your on-save function—see this commit.

Optional: rename "plugins" to "modules"

This is a purely cosmetic change, but if you'd like to stay in line with new projects, the change is a simple find-and-replace.

---

This discussion was created from the release v1.8.0.