Charon/.github/skills/docker-start-dev.SKILL.md

name, version, description, author, license, tags, compatibility, requirements, environment_variables, parameters, outputs, metadata

name	version	description	author	license	tags	compatibility	requirements	environment_variables	parameters	outputs	metadata
docker-start-dev	1.0.0	Starts the Charon development Docker Compose environment with all required services	Charon Project	MIT	docker development compose	os shells linux darwin bash	name version optional docker >=24.0 false name version optional docker-compose >=2.0 false			name type description exit_code integer 0 on success, non-zero on failure	category subcategory execution_time risk_level ci_cd_safe requires_network idempotent docker environment medium low false true true

Docker: Start Development Environment

Overview

Starts the Charon development Docker Compose environment in detached mode. This brings up all required services including the application, database, CrowdSec, and any other dependencies defined in .docker/compose/docker-compose.dev.yml.

Prerequisites

• Docker Engine installed and running
• Docker Compose V2 installed
• .docker/compose/docker-compose.dev.yml file in repository
• Network access (for pulling images)
• Sufficient system resources (CPU, memory, disk)

Usage

Basic Usage

.github/skills/docker-start-dev-scripts/run.sh

Via Skill Runner

.github/skills/scripts/skill-runner.sh docker-start-dev

Via VS Code Task

Use the task: Docker: Start Dev Environment

Parameters

This skill accepts no parameters. Services are configured in .docker/compose/docker-compose.dev.yml.

Environment Variables

This skill uses environment variables defined in:

• .env (if present)
• .docker/compose/docker-compose.dev.yml environment section
• Shell environment

Outputs

• Success Exit Code: 0 - All services started successfully
• Error Exit Codes: Non-zero - Service startup failed
• Console Output: Docker Compose logs and status

Output Example

[+] Running 5/5
 ✔ Network charon-dev_default        Created
 ✔ Container charon-dev-db-1         Started
 ✔ Container charon-dev-crowdsec-1   Started
 ✔ Container charon-dev-app-1        Started
 ✔ Container charon-dev-caddy-1      Started

What Gets Started

Services defined in .docker/compose/docker-compose.dev.yml:

1. charon-app: Main application container
2. charon-db: SQLite or PostgreSQL database
3. crowdsec: Security bouncer
4. caddy: Reverse proxy (if configured)
5. Other Services: As defined in compose file

Service Startup Order

Docker Compose respects depends_on directives:

1. Database services start first
2. Security services (CrowdSec) start next
3. Application services start after dependencies
4. Reverse proxy starts last

Examples

Example 1: Start Development Environment

# Start all development services
.github/skills/docker-start-dev-scripts/run.sh

# Verify services are running
docker compose -f .docker/compose/docker-compose.dev.yml ps

Example 2: Start and View Logs

# Start services in detached mode
.github/skills/docker-start-dev-scripts/run.sh

# Follow logs from all services
docker compose -f .docker/compose/docker-compose.dev.yml logs -f

Example 3: Start and Test Application

# Start development environment
.github/skills/docker-start-dev-scripts/run.sh

# Wait for services to be healthy
sleep 10

# Test application endpoint
curl http://localhost:8080/health

Service Health Checks

After starting, verify services are healthy:

# Check service status
docker compose -f .docker/compose/docker-compose.dev.yml ps

# Check specific service logs
docker compose -f .docker/compose/docker-compose.dev.yml logs app

# Execute command in running container
docker compose -f .docker/compose/docker-compose.dev.yml exec app /bin/sh

Port Mappings

Default development ports (check .docker/compose/docker-compose.dev.yml):

• 8080: Application HTTP
• 8443: Application HTTPS (if configured)
• 9000: Admin panel (if configured)
• 3000: Frontend dev server (if configured)

Detached Mode

The -d flag runs containers in detached mode:

• Services run in background
• Terminal is freed for other commands
• Use docker compose logs -f to view output

Error Handling

Common issues and solutions:

Port Already in Use

Error: bind: address already in use

Solution: Stop conflicting service or change port in compose file

Image Pull Failed

Error: failed to pull image

Solution: Check network connection, authenticate to registry

Insufficient Resources

Error: failed to start container

Solution: Free up system resources, stop other containers

Configuration Error

Error: invalid compose file

Solution: Validate compose file with docker compose config

Post-Startup Verification

After starting, verify:

1. All Services Running:

   docker compose -f .docker/compose/docker-compose.dev.yml ps
   

2. Application Accessible:

   curl http://localhost:8080/health
   

3. No Error Logs:

   docker compose -f .docker/compose/docker-compose.dev.yml logs --tail=50
   

Related Skills

• docker-stop-dev - Stop development environment
• docker-prune - Clean up Docker resources
• integration-test-all - Run integration tests

Notes

• Idempotent: Safe to run multiple times (recreates only if needed)
• Resource Usage: Development mode may use more resources than production
• Data Persistence: Volumes persist data across restarts
• Network Access: Requires internet for initial image pulls
• Not CI/CD Safe: Intended for local development only
• Background Execution: Services run in detached mode

Troubleshooting

Services Won't Start

1. Check Docker daemon: docker info
2. Validate compose file: docker compose -f .docker/compose/docker-compose.dev.yml config
3. Check available resources: docker stats
4. Review logs: docker compose -f .docker/compose/docker-compose.dev.yml logs

Slow Startup

• First run pulls images (may take time)
• Subsequent runs use cached images
• Use docker compose pull to pre-pull images

Service Dependency Issues

• Check depends_on in compose file
• Add healthchecks for critical services
• Increase startup timeout if needed

---

Last Updated: 2025-12-20 Maintained by: Charon Project Compose File: .docker/compose/docker-compose.dev.yml