This template Rails application provides a starting point for developing a new
Rails API application using the
iknow_view_models library. It
provides a highly opinionated framework and tools for constructing a new
API-based application in our preferred style. Additionally, it serves as a guide
for the parts of the application framework that we consider general purpose
enough that they should be abstracted and extracted into shared library code
before we start to maintain more than one application based on it.
This application is packaged and its dependencies supplied using Nix. If you prefer not to install Nix directly on your workstation, you can also develop using the supplied Docker Compose wrapper, which encapsulates the application and its dependencies in containers. For each aspect of the following instructions, follow either the "Docker Compose" or "Nix Shell" section depending which option you prefer.
Run the application together with the services using docker-compose up in the
root of the repository.
Enter a Nix shell in the Rails root directory with nix-shell. If you want, you
can make this transparent using (for example) direnv and lorri. Before the
first run, ensure the database is present and migrated with bundle exec rails db:prepare. Start the application with bundle exec rails s -p 3001.
Docker Compose: Run commands in the context of the backend container, for
example: docker-compose exec backend bundle exec rails db:migrate.
Nix Shell: Run commands directly with bundle exec, for example: bundle exec rails db:migrate.
The application environment depends on several services: Postgres, OpenSearch, Memcached and Redis. These are likewise supplied by the Nix environment. To launch the services:
Docker Compose: The services are already run in the top level
docker-compose.yml, which is configured for their state to be persisted in a
persistent Docker volume.
Nix Shell: You can start the services using the helper nix/start-services
which launches the services using a Procfile runner. The services' state will be
persisted in the project's tmp/ directory.
Bundled gems are provided via a Nix bundlerEnv (see nix/demoapp.nix for more
details). The practical consequence of this is that when updating Gemfile and
Gemfile.lock to add or change dependencies, you must also use bundix to
update gemset.nix. A convenience script bundleLock is included to make this
easier, which is equivalent to bundle lock in a typical Ruby installation.
Docker Compose: docker-compose exec backend bundleLock
Nix Shell: bundleLock
After updating the lock file, the bundled environment needs to be recreated:
Docker Compose: Rebuild and re-launch the container with docker-compose up --build.
Nix Shell: Exit and re-enter the nix shell.