Files

T

alex e7819bfc82 feat: implement docker infrastructure (US-001)

- Add docker-compose.yml with postgres, redis, api, and web services
- Add multi-stage Dockerfile for API (Python 3.11)
- Add multi-stage Dockerfile for web (Node.js 20 + nginx)
- Add Makefile with common development commands
- Add .env.example with all required environment variables
- Add placeholder pyproject.toml and package.json for builds
- Configure health checks for all services
- Setup persistent volumes for postgres, redis, and repos
- Run services as non-root users

2026-05-16 17:44:39 +00:00

2.3 KiB

Raw Permalink Blame History

Tool Instance Management Specification

Purpose

Launch, monitor, and manage development tool instances in Docker containers.

Requirements

Requirement: Tool Instance Creation

The system SHALL create and launch tool instances from repositories.

Scenario: Launch tool

GIVEN an authenticated user with a project and repository
WHEN they create a tool instance
THEN:
1. A unique subdomain is generated: {tool-name}-{tool-id}.hq.local
2. The Docker Compose template is rendered with project values
3. docker compose up -d is executed
4. Container ID and status are stored

Requirement: Tool Lifecycle

The system SHALL manage tool lifecycle operations.

Scenario: Stop tool

GIVEN a running tool instance
WHEN the user stops it
THEN docker compose stop is executed
AND status is updated to "stopped"

Scenario: Start tool

GIVEN a stopped tool instance
WHEN the user starts it
THEN docker compose start is executed
AND status is updated to "running"

Scenario: Delete tool

GIVEN a tool instance
WHEN the user deletes it
THEN the container and volumes are removed
AND the database record is deleted

Requirement: Traefik Integration

The system SHALL auto-generate Traefik labels for routing.

Scenario: Route generation

GIVEN a running tool instance
THEN these labels are set:
- traefik.enable=true
- traefik.http.routers.{tool_id}.rule=Host(\{subdomain}.hq.local`)`
- traefik.http.routers.{tool_id}.entrypoints=web
- traefik.http.services.{tool_id}.loadbalancer.server.port={port}

Requirement: Status Monitoring

The system SHALL track tool status.

Scenario: Status check

GIVEN a tool instance
WHEN status is queried
THEN the real-time container status is returned:
- pending, building, running, stopped, error

Requirement: Log Access

The system SHALL provide access to container logs.

Scenario: View logs

GIVEN a tool instance
WHEN logs are requested
THEN the last 100 lines are returned
AND live streaming is available via WebSocket

Dependencies

tool-types (tool definitions)
git-repo (repository access)
project-management (project context)
Docker runtime
Traefik reverse proxy

Quality Gates

pytest must pass
mypy . must pass
ruff check . must pass
npm run typecheck must pass
npm run lint must pass

2.3 KiB Raw Permalink Blame History