Archon/Makefile
Wirasm 86dd1b0749
Improve development environment with Docker Compose profiles (#435)
* Add improved development environment with backend in Docker and frontend locally

- Created dev.bat script to run backend services in Docker and frontend locally
- Added docker-compose.backend.yml for backend-only Docker setup
- Updated package.json to run frontend on port 3737
- Fixed api.ts to use default port 8181 instead of throwing error
- Script automatically stops production containers to avoid port conflicts
- Provides instant HMR for frontend development

* Refactor development environment setup: replace dev.bat with Makefile for cross-platform support and enhanced commands

* Enhance development environment: add environment variable checks and update test commands for frontend and backend

* Improve development environment with Docker Compose profiles

This commit enhances the development workflow by replacing the separate
docker-compose.backend.yml file with Docker Compose profiles, fixing
critical service discovery issues, and adding comprehensive developer
tooling through an improved Makefile system.

Key improvements:
- Replace docker-compose.backend.yml with cleaner profile approach
- Fix service discovery by maintaining consistent container names
- Fix port mappings (3737:3737 instead of 3737:5173)
- Add make doctor for environment validation
- Fix port configuration and frontend HMR
- Improve error handling with .SHELLFLAGS in Makefile
- Add comprehensive port configuration via environment variables
- Simplify make dev-local to only run essential services
- Add logging directory creation for local development
- Document profile strategy in docker-compose.yml

These changes provide three flexible development modes:
- Hybrid mode (default): Backend in Docker, frontend local with HMR
- Docker mode: Everything in Docker for production-like testing
- Local mode: API server and UI run locally

Co-authored-by: Zak Stam <zaksnet@users.noreply.github.com>

* Fix make stop command to properly handle Docker Compose profiles

The stop command now explicitly specifies all profiles to ensure
all containers are stopped regardless of how they were started.

* Fix README to document correct make commands

- Changed 'make lint' to 'make lint-frontend' and 'make lint-backend'
- Removed non-existent 'make logs-server' command
- Added 'make watch-mcp' and 'make watch-agents' commands
- All documented make commands now match what's available in Makefile

* fix: Address critical issues from code review #435

- Create robust environment validation script (check-env.js) that properly parses .env files
- Fix Docker healthcheck port mismatch (5173 -> 3737)
- Remove hard-coded port flags from package.json to allow environment configuration
- Fix Docker detection logic using /.dockerenv instead of HOSTNAME
- Normalize container names to lowercase (archon-server, archon-mcp, etc.)
- Improve stop-local command with port-based fallback for process killing
- Fix API configuration fallback chain to include VITE_PORT
- Fix Makefile shell variable expansion using runtime evaluation
- Update .PHONY targets with comprehensive list
- Add --profile flags to Docker Compose commands in README
- Add VITE_ARCHON_SERVER_PORT to docker-compose.yml
- Add Node.js 18+ to prerequisites
- Use dynamic ports in Makefile help messages
- Add lint alias combining frontend and backend linting
- Update .env.example documentation
- Scope .gitignore logs entry to /logs/

Co-Authored-By: Claude <noreply@anthropic.com>

* Fix container name resolution for MCP server

- Add dynamic container name resolution with three-tier strategy
- Support environment variables for custom container names
- Add service discovery labels to docker-compose services
- Update BackendStartupError with correct container name references

* Fix frontend test failures in API configuration tests

- Update environment variable names to use VITE_ prefix that matches production code
- Fix MCP client service tests to use singleton instance export
- Update default behavior tests to expect fallback to port 8181
- All 77 frontend tests now pass

* Fix make stop-local to avoid Docker daemon interference

Replace aggressive kill -9 with targeted process termination:
- Filter processes by command name (node/vite/python/uvicorn) before killing
- Use graceful SIGTERM instead of SIGKILL
- Add process verification to avoid killing Docker-related processes
- Improve logging with descriptive step messages

* refactor: Simplify development workflow based on comprehensive review

- Reduced Makefile from 344 lines (43 targets) to 83 lines (8 essential targets)
- Removed unnecessary environment variables (*_CONTAINER_NAME variables)
- Fixed Windows compatibility by removing Unix-specific commands
- Added security fixes to check-env.js (path validation)
- Simplified MCP container discovery to use fixed container names
- Fixed 'make stop' to properly handle Docker Compose profiles
- Updated documentation to reflect simplified workflow
- Restored original .env.example with comprehensive Supabase key documentation

This addresses all critical issues from code review:
- Cross-platform compatibility 
- Security vulnerabilities fixed 
- 81% reduction in complexity 
- Maintains all essential functionality 

All tests pass: Frontend (77/77), Backend (267/267)

* feat: Add granular test and lint commands to Makefile

- Split test command into test-fe and test-be for targeted testing
- Split lint command into lint-fe and lint-be for targeted linting
- Keep original test and lint commands that run both
- Update help text with new commands for better developer experience

* feat: Improve Docker Compose detection and prefer modern syntax

- Prefer 'docker compose' (plugin) over 'docker-compose' (standalone)
- Add better error handling in Makefile with proper exit on failures
- Add Node.js check before running environment scripts
- Pass environment variables correctly to frontend in hybrid mode
- Update all documentation to use modern 'docker compose' syntax
- Auto-detect which Docker Compose version is available

* docs: Update CONTRIBUTING.md to reflect simplified development workflow

- Add Node.js 18+ as prerequisite for hybrid development
- Mark Make as optional throughout the documentation
- Update all docker-compose commands to modern 'docker compose' syntax
- Add Make command alternatives for testing (make test, test-fe, test-be)
- Document make dev for hybrid development mode
- Remove linting requirements until codebase errors are resolved

* fix: Rename frontend service to archon-frontend for consistency

Aligns frontend service naming with other services (archon-server, archon-mcp, archon-agents) for better consistency in Docker image naming patterns.

---------

Co-authored-by: Zak Stam <zakscomputers@hotmail.com>
Co-authored-by: Zak Stam <zaksnet@users.noreply.github.com>
2025-08-22 17:18:10 +03:00

110 lines
3.3 KiB
Makefile

# Archon Makefile - Simple, Secure, Cross-Platform
SHELL := /bin/bash
.SHELLFLAGS := -ec
# Docker compose command - prefer newer 'docker compose' plugin over standalone 'docker-compose'
COMPOSE ?= $(shell docker compose version >/dev/null 2>&1 && echo "docker compose" || echo "docker-compose")
.PHONY: help dev dev-docker stop test test-fe test-be lint lint-fe lint-be clean install check
help:
@echo "Archon Development Commands"
@echo "==========================="
@echo " make dev - Backend in Docker, frontend local (recommended)"
@echo " make dev-docker - Everything in Docker"
@echo " make stop - Stop all services"
@echo " make test - Run all tests"
@echo " make test-fe - Run frontend tests only"
@echo " make test-be - Run backend tests only"
@echo " make lint - Run all linters"
@echo " make lint-fe - Run frontend linter only"
@echo " make lint-be - Run backend linter only"
@echo " make clean - Remove containers and volumes"
@echo " make install - Install dependencies"
@echo " make check - Check environment setup"
# Install dependencies
install:
@echo "Installing dependencies..."
@cd archon-ui-main && npm install
@cd python && uv sync
@echo "✓ Dependencies installed"
# Check environment
check:
@echo "Checking environment..."
@node -v >/dev/null 2>&1 || { echo "✗ Node.js not found (require Node 18+)."; exit 1; }
@node check-env.js
@echo "Checking Docker..."
@docker --version > /dev/null 2>&1 || { echo "✗ Docker not found"; exit 1; }
@$(COMPOSE) version > /dev/null 2>&1 || { echo "✗ Docker Compose not found"; exit 1; }
@echo "✓ Environment OK"
# Hybrid development (recommended)
dev: check
@echo "Starting hybrid development..."
@echo "Backend: Docker | Frontend: Local with hot reload"
@$(COMPOSE) --profile backend up -d --build
@set -a; [ -f .env ] && . ./.env; set +a; \
echo "Backend running at http://$${HOST:-localhost}:$${ARCHON_SERVER_PORT:-8181}"
@echo "Starting frontend..."
@cd archon-ui-main && \
VITE_ARCHON_SERVER_PORT=$${ARCHON_SERVER_PORT:-8181} \
VITE_ARCHON_SERVER_HOST=$${HOST:-} \
npm run dev
# Full Docker development
dev-docker: check
@echo "Starting full Docker environment..."
@$(COMPOSE) --profile full up -d --build
@echo "✓ All services running"
@echo "Frontend: http://localhost:3737"
@echo "API: http://localhost:8181"
# Stop all services
stop:
@echo "Stopping all services..."
@$(COMPOSE) --profile backend --profile frontend --profile full down
@echo "✓ Services stopped"
# Run all tests
test: test-fe test-be
# Run frontend tests
test-fe:
@echo "Running frontend tests..."
@cd archon-ui-main && npm test
# Run backend tests
test-be:
@echo "Running backend tests..."
@cd python && uv run pytest
# Run all linters
lint: lint-fe lint-be
# Run frontend linter
lint-fe:
@echo "Linting frontend..."
@cd archon-ui-main && npm run lint
# Run backend linter
lint-be:
@echo "Linting backend..."
@cd python && uv run ruff check --fix
# Clean everything (with confirmation)
clean:
@echo "⚠️ This will remove all containers and volumes"
@read -p "Are you sure? (y/N) " -n 1 -r; \
echo; \
if [[ $$REPLY =~ ^[Yy]$$ ]]; then \
$(COMPOSE) down -v --remove-orphans; \
echo "✓ Cleaned"; \
else \
echo "Cancelled"; \
fi
.DEFAULT_GOAL := help