Local development

Local Development

The local Goat development environment starts the entire required set of services and processes with a single command.

Main script:

herd/dev.goat

coordinates, among other things:

• PostgreSQL,
• pgAdmin,
• the application backend,
• code generation,
• CLI building,
• fixture loading,
• Angular frontend building,
• watching for changes in the sources and model.

This means you do not need to manually start each part of the project separately.

Starting the Environment

To start working, run:

goat run:script --path=herd/dev.goat

The script prepares a complete development environment and remains running, watching for changes in the project.

Once initialization is complete, you can immediately work with the backend, frontend, and local database.

What Happens During Startup

When starting the environment, dev.goat performs the successive steps required to prepare the application.

In simplified form, the process looks like this:

infrastructure startup
        ↓
core:build
        ↓
code generation
        ↓
CLI building
        ↓
waiting for PostgreSQL
        ↓
fixture loading
        ↓
starting the application and watchers

The most important steps include:

1. building the application core using core:build,
2. generating code based on the current model,
3. building the generated application's CLI,
4. starting PostgreSQL and checking its availability,
5. loading data from herd/fixture.goat,
6. starting the backend,
7. starting the frontend build process,
8. beginning to watch for changes in the project.

This ensures that the local environment is prepared consistently and does not depend on a manually executed sequence of commands.

Local Services

After starting the environment, the following services are available:

The application is available on port 8080, PostgreSQL on 5433, and pgAdmin on 5050.

Automatic Response to Changes

One of the main advantages of herd/dev.goat is watching the project and automatically performing the appropriate operations after source changes.

You do not need to manually run the generator or build process every time.

Model Change

Changing:

herd/_model.goat

causes the generation process to run again.

In simplified form:

model change
      ↓
code regeneration
      ↓
application update

This allows you to focus on the model while working on the domain structure, and the development environment will take care of preparing the resulting changes.

Backend Changes

Changes in backend sources or core tools trigger rebuilding the relevant application components.

This applies, among other things, to the application's source code and:

scripts/

After detecting a change, the environment may run again:

core:build

and prepare the current version of the application.

You therefore do not need to restart the entire environment after every backend change.

Frontend Changes

The Angular frontend runs in watch mode.

After changing frontend code, the build process automatically prepares the current version of the application.

The typical cycle therefore looks like this:

Angular component change
        ↓
automatic build
        ↓
application refresh

This allows you to work on the frontend without manually running the full generation process.

Working with generated code

Code generated by Goat can be edited normally during development.

The generator is intended to speed up work, not force every change to be made through the model.

You can therefore:

• modify the model and let Goat generate the resulting elements,
• modify a template if a given change should apply to many similar places,
• edit the application code directly if the change is specific to a particular feature.

After each major regeneration, it is worth checking:

git diff

to see the actual scope of changes.

One-time application setup

You do not always need a full development environment running in the background.

If you only want to prepare the current version of the generated application, you can run:

goat core:build
goat re

The first command prepares the current application core, while the second performs generation based on the model and project configuration.

This is useful, among other things:

• before reviewing changes in Git,
• before running a single test,
• while debugging the generator,
• when you do not need PostgreSQL, pgAdmin, and watchers,
• in simple automation scripts.

Typical workflow

In day-to-day work, it is usually enough to start the environment once:

goat run:script --path=herd/dev.goat

and then work on the project as usual.

Example:

start dev.goat
      ↓
modify _model.goat
      ↓
automatic regeneration
      ↓
modify generated code or frontend
      ↓
automatic rebuild
      ↓
check the result in the application

At the end, it is worth checking:

git diff
git status

and running the full test suite:

goat run:script --path=herd/test.goat

Fixtures during development

During the initial environment startup, the following is loaded:

herd/fixture.goat

This allows the application to start immediately with sample data and documentation appropriate for the version of the project being used.

If you modify fixtures while working and want to load them again, you can do so manually through the application CLI.

Do not remove the cache while the environment is running

While working, dev.goat may use cache directories and persistent data used by containers and development processes.

Do not remove them manually while the environment is running.

This may lead to:

• loss of local data,
• errors in running processes,
• an inconsistent container state,
• unexpected issues during subsequent rebuilds.

If you need to clean the environment, first stop the running processes, then use dedicated commands or scripts intended to clean a specific part of the project.

Most important rule

herd/dev.goat should be the main entry point for local project work.

Instead of manually managing separate Docker, backend, frontend, generator, and database processes, you run a single workflow that prepares the environment and responds to code changes.

This keeps local development fast, repeatable, and as consistent as possible across different development workstations.