skills.rest
lablup
lablupOFFICIAL
Explore all skills by this author →
WebsiteGitHub

halfstack

Diagnose and fix Docker Compose halfstack development environment issues.

672|181|Updated Oct 6, 2016
Search Tags:#dev environment#docker compose#Troubleshooting#etcd#postgreSQL#graphqL#halfstack
One-click install
npx skills add https://github.com/lablup/backend.ai --skill halfstack
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: halfstack
Source: https://github.com/lablup/backend.ai/tree/main/.claude/skills/halfstack
Command: npx skills add https://github.com/lablup/backend.ai --skill halfstack

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Backend.AI developers frequently hit broken local development environments: Docker Compose services that fail to start, config files accidentally created as directories, stale supergraph schemas, and port or secret mismatches across component configs. This Skill diagnoses and directly fixes these halfstack issues instead of just reporting them.

Core Features & Use Cases

  • Compose Service Recovery: Detect missing or mis-mapped config files (prometheus.yaml, supergraph.graphql, etc.), remove wrongly-created directories, restore files from configs/ sources, and restart services.
  • Direct State Inspection: Query PostgreSQL (alembic versions, databases), Valkey (keys, info), etcd (config prefixes), and MinIO health via docker exec commands.
  • Supergraph Regeneration: Regenerate the federated GraphQL schema after GQL changes and restart the Hive Gateway, with a git-based fallback to the last known-good schema.
  • Use Case: After switching branches, docker compose up fails because supergraph.graphql became a directory. The Skill stops the stack, removes the directory, copies the correct file, and brings services back up.

Quick Start

Ask the assistant to diagnose why the halfstack Docker Compose services are failing to start and fix the underlying config or service issue.

Frequently Asked Questions about halfstack

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix Docker Compose services that keep restarting in Backend.AI halfstack?▼

Check service status with docker compose -f docker-compose.halfstack.current.yml ps, then read logs for the failing service. Most failures come from missing config files or directories created where files should be; remove the directory, copy the correct file from configs/, and restart.

Why does Docker Compose create a directory instead of mounting my config file?▼

When a config file declared in the compose configs section is missing, Docker creates a directory at that path. Once the directory exists, copying the file over it will not work; you must stop the service, remove the directory with rm -rf, copy the correct file, and restart.

How do I regenerate the GraphQL supergraph after schema changes?▼

Run ./scripts/generate-graphql-schema.sh, copy docs/manager/graphql-reference/supergraph.graphql and configs/graphql/gateway.config.ts to the project root, then restart the backendai-half-apollo-router service. If generation fails, restore the last known-good schema from git.

How do I inspect PostgreSQL, Valkey, or etcd state in the halfstack?▼

Use docker exec against the service containers: psql -U postgres -d backend for PostgreSQL, valkey-cli for Valkey, and etcdctl for etcd. The Skill provides ready commands for queries like checking alembic versions, listing keys, and endpoint health.

Which Docker Compose profiles enable optional halfstack services?▼

The telemetry profile adds the OTel collector and Loki, observability adds the full Grafana, Tempo, Pyroscope, and exporter stack, and storage adds MinIO. Pass --profile <name> to docker compose up, and pass the same profiles when tearing down.

What must stay consistent across Backend.AI component config files?▼

PostgreSQL, Valkey, and etcd ports in the compose file must match the corresponding values in manager.toml, agent.toml, storage-proxy.toml, app-proxy configs, and webserver.conf. The app-proxy coordinator and worker must also share identical api_secret, jwt_secret, and permit_hash.secret values.

Related Skills

Explore More Software Engineering Skills→
de6elingde6eling
1

design-setup

Scan repositories to generate design-compose configuration files.

Community
Intermediate
labluplablup
130

backend-ai-guide

Explain Backend.AI architecture and components using official documentation.

Official
Advanced
williamzujkowskiwilliamzujkowski
6

Observability Unified Dashboard

Designs unified observability dashboards correlating metrics, logs, and traces across Prometheus, Loki, Tempo, and Grafana 11.

Community
Advanced
CowboyLogicCowboyLogic

docker-devops

Automate Docker Compose deployment workflows for multi-service applications.

Official
Advanced