arad / documentation / development
This document describes how to perform common tasks while developing ARAD.
There are a few scripts in the scripts directory that provide convenience methods for developers.
This script synchronizes common code across the back-end services.
arad $ scripts/sync
This script provides the ability to interact with the local stack.
This will build your docker images. It is required before up.
arad $ scripts/local build
This starts a development stack. Healthchecks at each layer block the next from starting. Read docker-compose.yml for more information.
arad $ scripts/local up
This stops a development stack from another terminal, and removes the stack's containers if run a second time.
arad $ scripts/local down
This will update all the poetry.lock files in the backend. Warning: test well if you use this. Updating individual solitary dependencies as required is much safer.
arad $ scripts/local relock
This will execute a command in all backend services.
arad $ scripts/local exec poetry env info
This will clean up some intermediate Docker images.
arad $ scripts/local prune
This will remove containers spawned by docker run without the --rm parameter.
arad $ scripts/local rm
This will fetch type information from the OpenAPI definitions generated by the back-end and create types in the front-end.
arad $ scripts/local types
This command will reset a local Arad stack, recreating the database.
arad $ scripts/local nuke
This command starts an interactive shell in the back-end of your choice.
arad $ scripts/local repl identity
The database script provides access to common tasks involving the database.
This command will create a PostgreSQL database suitable for development and install the pgcrypto extension.
arad $ scripts/database create
This command will destroy the existing database.
arad $ scripts/database drop
This command will run any pending migrations.
arad $ scripts/database migrate
This command will attept to generate new migrations from changes in database/models.py.
arad $ scripts/database generate-migrations
This command will generate an empty migration for whatever purposes you may need.
arad $ scripts/database empty-migration
First we'll add the package without installing it, since the changes won't persist.
arad $ scripts/local exec poetry add <package> -vv --lock
To make these changes stick, we'll need to rebuild our images. Layer caching won't help us much, since thd slow step is poetry install.
arad $ scripts/local build
That's it! You're ready to develop using your new package.
Here we add black to identity, as a test dependency, without installing.
docker compose run --rm identity poetry add black -vv --group test --lock
Next, we'll want to rebuild:
arad $ scripts/sync && scripts/local build
It's convenient to sync before building in case you've made changes to common files. Sometimes I forget. If others find this annoying, someone should open a PR to sync from the build command itself.