Development Setup

This page covers the local environment needed to run, change, and validate the repository.

Audience: Developer

Context: Use this page after you understand the architecture and want a working local contributor setup.

Practical Usage

Repository-supported setup with uv:

git clone https://github.com/Garudex-Labs/Caracal.git
cd Caracal
uv venv
source .venv/bin/activate
uv sync --locked --extra dev
caracal --version

Start the local infrastructure:

make infra-up

Or run the contributor convenience target:

make setup-dev

Core Explanation

The local development environment has three moving parts:

• Python dependencies managed through uv.lock
• Docker Compose infrastructure for PostgreSQL and Redis
• the host caracal command, which then orchestrates the full runtime stack

Important Makefile targets:

Target	Purpose
make deps	install runtime dependencies
make deps-dev	install runtime and development dependencies
make infra-up	start PostgreSQL and Redis
make infra-down	stop PostgreSQL and Redis
make runtime-up	wrapper for caracal up
make runtime-cli	wrapper for caracal cli
make runtime-flow	wrapper for caracal flow

Internal Behavior

make setup-dev ultimately does three things:

1. installs dependencies with uv
2. starts local PostgreSQL and Redis through deploy/docker-compose.yml
3. installs the local package as a uv tool so caracal is available on the host

That setup mirrors the supported runtime model instead of bypassing it.

Edge Cases And Constraints

• The docs application under docs/ is a separate Node-based workflow and is not part of the Python runtime bootstrap.
• Docker Compose support is required even in development because the runtime assumes containerized services.
• caracal up may choose a build-based or image-based compose path depending on the environment and discovered compose file.

Related Concepts

• Contributing
• Testing
• Runtime Model