alex
e7819bfc82
- 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
91 lines
2.3 KiB
Markdown
91 lines
2.3 KiB
Markdown
# 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
|