Development Quickstart

Use this page for a fast first-run Core setup. Detailed Core configuration lives in the backend and frontend guides.

Prerequisites

Nix, via Determinate Systems for local development tooling.
Docker Desktop (or compatible Docker runtime), configured using the Development Environments guide.
AWS CLI configured for company SSO access.
core.test resolving to 127.0.0.1 for the local app hostname.

Quickstart

1) Prepare the local shell and backend services (repository root)

These commands set up your local toolchain, create a local environment file, authenticate to AWS and the private Docker registry, start the Docker stack, and bootstrap Laravel.

shell

# Load the project development environment (Node, ni/nr aliases, and other tooling)
nix develop

# Run first-run setup
just setup

# Open a shell inside the PHP application container
just shell-core-web

Core's Docker configuration sets APP_URL=http://core.test and maps the web service to host port 80.

Use just stop to stop the local services, and just restart to restart them. These commands use docker-compose with AWS_PROFILE=internal-services and the default services from the Compose file.

just setup signs Docker in to the private ECR registry, then uses just start-with-wait before running Composer and Laravel bootstrap commands.

Common setup helpers are also available through just:

shell

just setup-env-file
just setup-hosts
just aws-login
just aws-check
just ecr-login
just start
just start-with-wait
just shell-core-web
just composer-install
just migrate
just storage-link
just seed-testing-local

The seed command keeps the underlying script's destructive database prompt.

Reporting MQ consumer

The reporting MQ consumer is optional for local development. The default AWS_PROFILE=internal-services docker-compose up -d command does not start core.mq-consumer, which avoids noisy Laravel logs when the reporting MQ server is not needed or is being booted by the reporting service repository.

Start it only when you need to consume reporting status updates from this repository:

shell

AWS_PROFILE=internal-services docker-compose --profile reporting-mq up -d

2) Bootstrap the Laravel app (inside `core.web`)

These commands install PHP dependencies, apply database migrations, and create the public storage symlink used by the app.

shell

# Install backend PHP dependencies from composer.lock
just composer-install

# Run database migrations with verbose output
just migrate

# Link storage/app/public to public/storage for locally served files
just storage-link

# Setup AI tooling
just boost-install

3) Build frontend assets (back on the host machine inside `nix develop`)

These commands install frontend dependencies and compile production-ready assets.

shell

# Install frontend dependencies using ni (npm in this repository)
ni

# Build frontend assets used by the application
nr build

Detailed Guides

Backend setup: docs/backend/setup.md
Frontend setup and development: docs/frontend/development.md
Backend testing: docs/backend/testing.md

Optional: Auto-Load Shell With direnv

To auto-load nix develop when entering this repository, use direnv with nix-direnv. You can do this using our Nix Development Profiles system for installing dependencies.

shell

echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
cp .envrc.example .envrc
direnv allow