Dev Setup

Guidance for setting up a developer. Last updated 2025-08-06.

“I” and “me” etc, below, refers to Byron.

Issues that this doesn’t cover:

  • I’ve typically set up my IDE to reformat the file upon save using the ScalaFmt formatter with a specified config. Need to integrate that setup, below.
  • Varun and I have been trying to figure out whether VSCode can replace IntelliJ. No conclusion yet.

Caveats

  • This project is now more than a decade old. Scala, Play, and IntelliJ have all evolved substantially over that period of time. As new developers come on board, it may be appropriate to question my habits WRT to development. Examples:
    • Does it still make sense to develop with two windows – one for the IDE and one for SBT? Why not let IntelliJ run OAT?
    • Is there a better way to test with the database?
  • There are test suites for the queries and the running system that have been allowed to attrify to the point they are probably useless.
  • There are some things that Byron should have figured out but hasn’t:
    • How to put libraries on a server for common usage.
    • How to reliably debug a project (especially OAT) while using SBT.

Basics

  1. Create a directory, oatdev, at a convenient place.
  2. mkdir oatdev/bin
  3. Add export OAT_HOME=<PATH_TO_OATDEV_DIR> to ~/.zshenv.
  4. Add ${OAT_HOME}/bin to the PATH variable in ~/.zshenv.

Install Software

Install the following software. If you’re on a Mac, the brew package manager is an easy way to go. It feels like these could be run in parallel, but not a good idea because dependent packages could be installed multiple times.

  1. Start downloading the IntelliJ IDE Community Edition installer.
    • I have MFCF pay for the Ultimate Edition for me.
  2. Install or update brew
  3. brew install scala (Downloads openjdk@24 as a dependency; I’m currently using openjdk@17. In the limited testing I’ve done while documenting things, I haven’t noticed anything that breaks. But if things go sideways, …)
  4. brew install sbt
    • This is a build tool. I hate it and use mill when I can. But the main OAT project needs sbt.
  5. Install SourceTree gui for git (not required, but highly recommended)
  6. Install the IntelliJ IDE (download started earlier)
    • Open the .dmg and drag the app to Applications
    • Open the app
    • Go Settings -> Plugins and search the “marketplace” for “Scala”. Install the plugin.
  7. Install Mill
    • An alternative build tool used by most of my libraries and scripts.
    • It’s recommended to put a bootstrap script in each of your project folders. In practise, I put one in oat/bin (which is in my path).
    • cd ${OAT_HOME}/bin
    • curl -L https://repo1.maven.org/maven2/com/lihaoyi/mill-dist/1.0.2/mill-dist-1.0.2-mill.sh -o mill
    • chmod +x mill
    • echo "//| mill-version: 1.0.2" > build.mill
    • ./mill version will result in a bunch of download activity but then give 1.0.2
  8. brew install node
  9. npm install less -g

Set up the database

  1. brew install postgresql@14
    • brew services start postgresql@14 to so it restarts at each login
  2. Set up postgres config files:
    • Place this content in ~/.pg_service.conf, replacing USERID with your own userid.
    • Place this content in ~/.pgpass, substituting your own userid and passwords.
  3. Set up a local test database.
    • git clone ist-git@git.uwaterloo.ca:oat/oat-testdata.git
    • Follow the instructions in the README

Build libraries

Once upon a time we had a server where these libraries were placed so each developer didn’t have to build their own. That broke; haven’t been able to figure out why.

Starting directory for each of these is OAT_HOME.

  1. oat-validate: A library to validate values, collecting “all” the things that are wrong into a single error object. There are others but they either have dependencies or a DSL that I don’t like, so wrote my own.
    • git clone ist-git@git.uwaterloo.ca:oat/oat-validate.git
    • cd oat-validate
    • mill __.publishLocal. (Two underscores – that executes publishLocal in all subprojects; i.e. the one for the JVM and the one for Javascript.)
  2. oat-locales: Time zone stuff that is stripped down to just the parts we need; it’s huge otherwise. Needed by the Scala implementation of javatime.
    • git clone ist-git@git.uwaterloo.ca:oat/oat-locales.git
    • cd oat-locales
    • sbt publishLocal
  3. oatlibxp: A collection of cross-platform libraries that I use in a bunch of oat-related projects. Definitions of various id values, some testing utilities, extensions to base classes like String, Vector, etc. that are useful, etc.
    • git clone ist-git@git.uwaterloo.ca:oat/oatlibxp.git
    • cd oatlibxp
    • mill __.publishLocal (two underscores)
  4. oat-degreeAudit3: The degree audit tool.
    • git clone ist-git@git.uwaterloo.ca:oat/oat-degreeaudit3.git
    • cd oat-degreeAudit3
    • git checkout v0.7.1 (or other appropriate branch; As of 2025-08-06, degree audit is under active development and the current branch has not been merged with main.)
    • mill __.publishLocal (two underscores)
    • The build file makes a css file that it attempts to copy to the oat3 directory when you run the CLI. That will fail at this point.
  5. jsFacadeOptionBuilder: Help build a scala interface to a Javascript library.
    • git clone ist-git@git.uwaterloo.ca:oat/jsfacadeoptionbuilder.git
    • cd jsfacadeoptionbuilder
    • sbt publishLocal
  6. playFormsST: Emulate some stuff from the built-in Play templating language for use with the language we actually use. I’d like to get rid of it…
    • git clone ist-git@git.uwaterloo.ca:oat/playFormsST.git
    • cd playFormsST
    • sbt publishLocal

Build OAT

  1. git clone ist-git@git.uwaterloo.ca:oat/oat.git oat3 (Note extra parameter; this is the third instantiation of OAT (Python, Scala+Lift, Scala+Play))
  2. cd oat3
  3. git checkout oat4.2.1 (or whatever the current branch is)
  4. Place this content in a file named _oat/conf/passwords/local-dev.conf.
    • You’ll likely need to make the directory.
    • There is a script, start that takes local-dev as a parameter. It looks for that config file in this directory and uses it to start OAT. You’ll probably also (eventually) add config files for production and dev/stage here.
  5. Place this content in a file named _oat/conf/shared.local.conf. It’s called shared because it’s shared between many subprojects, not because it’s shared between developers. Perhaps the most useful config key here is oat.debug.user which determines the “logged in” userid when run locally. That user needs to be in the database as an OAT user. Some of the unit tests will fail for users other than bwbecker. It should probably have root permissions in the OAT permissions hierarchy so you have access to full functionality when running OAT.
  6. Fetch node/JS libraries:
    • cd oat3
    • npm install
    • This generates a bunch of deprecation warnings. See issue #2288.

Compile

  1. In oat3, ./start local-dev: This starts an sbt REPL with settings found in _oat/conf/passwords/local-dev.conf.
  2. compile – the first time will take a while to download all the dependencies. It hopefully, eventually, compiles successfully.
  3. Do some testing:
    • project xplatformJVM
    • test
    • repeat above for projects {xplatformJS, browser, server, wapp, wsvc}.
    • For wsvc you’ll get some failures because the test database does not have plan definitions for degree audit.

Run it

  1. It will need a file named generated.keystore for the SSL certificate. I’ve forgotten how to generate this and why there simply isn’t one in the repo. In any case, get a copy from another developer and put it at _oat/conf/generated.keystore.
  2. Quit and restart sbt. Type run. You should then be able to access OAT in a browser at https://localhost:9443

Notes:

  1. An IntelliJ compiler (for presentatation?) and the sbt compiler can be in conflict, resulting in recompiling everything when that’s not needed. In IntelliJ settings, go Build,Execution,Deployment -> Build Tools -> sbt and ensure that “Use separate compiler output paths” is checked. But setting this causes parts of the IDE to become non-functional. I’ve submitted a bug report but it’s not resolved yet. Probably best to NOT use this setting and put up with longer recompile times for now.