Skip to content

Modern Docker Management, Designed for Everyone

chore: container-based development workflow with hot reload and VS Code integration (#509)

Chase Baucomfd35854c87fa
diff --git a/.gitignore b/.gitignore
index 663daa19c..aba55c1c4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -32,6 +32,7 @@ tests/test-results/*
tests/.report/*
tests/.auth/
backend/.bin
+backend/build-errors.log
frontend/bun.lock
tests/bun.lock
tests/package-lock.json
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 000000000..c6422a79a
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,5 @@
+{
+ "recommendations": [
+ "actboy168.tasks"
+ ]
+}
\ No newline at end of file
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
new file mode 100644
index 000000000..2e925313d
--- /dev/null
+++ b/.vscode/tasks.json
@@ -0,0 +1,153 @@
+{
+ "version": "2.0.0",
+ "tasks": [
+ {
+ "label": "Start",
+ "type": "shell",
+ "command": "./scripts/development/dev.sh",
+ "args": ["start"],
+ "group": {
+ "kind": "build",
+ "isDefault": true
+ },
+ "presentation": {
+ "reveal": "silent",
+ "close": false,
+ "clear": false,
+ "echo": false,
+ "focus": false,
+ "showReuseMessage": false
+ },
+ "isBackground": true,
+ "detail": "Start the Docker development environment with hot reload"
+ },
+ {
+ "label": "Stop",
+ "type": "shell",
+ "command": "./scripts/development/dev.sh",
+ "args": ["stop"],
+ "group": "build",
+ "presentation": {
+ "reveal": "silent",
+ "close": false,
+ "clear": false,
+ "echo": false,
+ "focus": false,
+ "showReuseMessage": false
+ },
+ "isBackground": true,
+ "detail": "Stop the Docker development environment"
+ },
+ {
+ "label": "Restart",
+ "type": "shell",
+ "command": "./scripts/development/dev.sh",
+ "args": ["restart"],
+ "group": "build",
+ "presentation": {
+ "reveal": "silent",
+ "close": false,
+ "clear": false,
+ "echo": false,
+ "focus": false,
+ "showReuseMessage": false
+ },
+ "isBackground": true,
+ "detail": "Restart all services in the development environment"
+ },
+ {
+ "label": "Rebuild",
+ "type": "shell",
+ "command": "./scripts/development/dev.sh",
+ "args": ["rebuild"],
+ "group": "build",
+ "presentation": {
+ "reveal": "silent",
+ "close": false,
+ "clear": false,
+ "echo": false,
+ "focus": false,
+ "showReuseMessage": false
+ },
+ "isBackground": true,
+ "detail": "Rebuild containers and restart (useful after dependency changes)"
+ },
+ {
+ "label": "Clean",
+ "type": "shell",
+ "command": "./scripts/development/dev.sh",
+ "args": ["clean"],
+ "group": "build",
+ "presentation": {
+ "echo": true,
+ "reveal": "always",
+ "focus": true,
+ "panel": "dedicated",
+ "showReuseMessage": false,
+ "clear": true
+ },
+ "detail": "Remove all containers, networks, and volumes (WARNING: destructive)"
+ },
+ {
+ "label": "Logs",
+ "type": "shell",
+ "command": "./scripts/development/dev.sh",
+ "args": [
+ "logs",
+ "${input:logService}"
+ ],
+ "group": "test",
+ "presentation": {
+ "echo": true,
+ "reveal": "always",
+ "focus": true,
+ "panel": "dedicated",
+ "showReuseMessage": false,
+ "clear": true
+ },
+ "detail": "Select which service logs to view"
+ },
+ {
+ "label": "Open Frontend",
+ "type": "process",
+ "command": "open",
+ "args": ["http://localhost:3000"],
+ "group": "test",
+ "presentation": {
+ "reveal": "never",
+ "close": true,
+ "clear": false,
+ "echo": false,
+ "focus": false,
+ "showReuseMessage": false
+ },
+ "runOptions": {
+ "runOn": "default"
+ },
+ "isBackground": true,
+ "detail": "Open the frontend application in your default browser"
+ }
+ ],
+ "inputs": [
+ {
+ "id": "logService",
+ "description": "Which service logs to view",
+ "type": "pickString",
+ "options": [
+ {
+ "label": "All Services",
+ "value": ""
+ },
+ {
+ "label": "Frontend Only",
+ "value": "frontend"
+ },
+ {
+ "label": "Backend Only",
+ "value": "backend"
+ }
+ ],
+ "default": ""
+ }
+ ]
+}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2d7f330a7..a736f912e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,85 +1,244 @@
# Contributing to Arcane
-Thanks for helping make Arcane better! Contributions of all kinds are welcome.
+Thanks for helping make Arcane better! We've built a modern, streamlined development experience that gets you up and running in minutes.
-## Ways to Contribute
+## 🌟 Ways to Contribute
-- Reporting bugs: use the GitHub templates β€” Bug Report and Feature Request.
-- Suggesting features or improvements.
-- Code contributions (frontend or backend).
+- πŸ› **Report bugs** using our issue templates
+- πŸ’‘ **Suggest features** or improvements
+- πŸ”§ **Code contributions** (frontend, backend, DevOps)
+- πŸ“š **Documentation** improvements
+- 🌍 **Translations** via [Crowdin](https://crowdin.com/project/arcane-docker-management)
+- πŸ§ͺ **Testing** and quality assurance
-## Quick Start
+## πŸš€ Quick Start
-Prereqs:
+### Prerequisites
-- Go 1.25 and Docker
-- Node 24 and pnpm 10.15
+- **Docker & Docker Compose** (that's it! πŸŽ‰)
+- **VS Code** based IDE (recommended for the best developer experience)
-1. Fork and clone:
+> **πŸ’‘ Working Directory**: Unless otherwise specified, all commands in this guide should be run from the project root directory (`arcane/`).
- ```bash
- git clone https://github.com/<your-username>/arcane.git
- cd arcane
- ```
+### 1. Fork and Clone
+
+```bash
+git clone https://github.com/<your-username>/arcane.git
+cd arcane
+```
+
+### 2. Start Development Environment
+
+From the project root directory:
+
+```bash
+./scripts/development/dev.sh start
+```
+
+That's it! The development environment will automatically:
+- πŸ”₯ Start both frontend and backend with hot reload
+- 🐳 Handle all dependencies via Docker
+- πŸ“Š Set up health checks and monitoring
+- πŸ’Ύ Create persistent storage for your development data
+
+Access your development environment:
+- **Frontend**: http://localhost:3000 (SvelteKit with HMR)
+- **Backend**: http://localhost:3552 (Go with Air hot reload)
+
+## 🎯 VS Code Integration
+
+For the best development experience, we've included VS Code tasks and workspace configuration.
+
+### Recommended Extensions
+
+When you open the project in VS Code, you'll be prompted to install our recommended extensions. These provide:
+- Docker integration and management
+- Go language support with debugging
+- Svelte/TypeScript support
+- Integrated terminal management
+
+### One-Click Development Commands
-2. Create a branch:
+Use `Ctrl/Cmd+Shift+P` β†’ "Tasks: Run Task" to access:
+| Task | Description |
+|------|-------------|
+| **Start** | Start the development environment |
+| **Stop** | Stop all services |
+| **Restart** | Restart all services |
+| **Rebuild** | Rebuild containers (after dependency changes) |
+| **Clean** | Remove all containers and volumes |
+| **Logs** | Interactive log viewer with service selection |
+| **Open Frontend** | Launch frontend in browser |
+
+### Quick Build Shortcut
+
+Press `Ctrl/Cmd+Shift+B` to run the default build task (Start Environment).
+
+## πŸ” Development Workflow
+
+### Making Changes
+
+1. **Create a feature branch**:
```bash
- git switch -c feat/my-new-feature
+ git switch -c feat/my-awesome-feature
# or
git switch -c fix/issue-123
```
-3. Frontend (SvelteKit):
-
+2. **Start development** (from project root):
```bash
- cd frontend
- pnpm install
- pnpm dev
+ ./scripts/development/dev.sh start
+ # or use VS Code Task: "Start"
```
-4. Backend (Go + Gin):
-
+3. **Monitor logs** (choose your preferred method):
```bash
- go install github.com/air-verse/air@latest
- cd backend
- air
+ # Interactive selector
+ ./scripts/development/dev.sh logs
+
+ # Specific service
+ ./scripts/development/dev.sh logs frontend
+ ./scripts/development/dev.sh logs backend
+
+ # Or use VS Code Task: "Logs"
```
-## Code Style
+4. **Make your changes** - hot reload will automatically update:
+ - **Frontend**: Instant HMR via Vite
+ - **Backend**: Auto-rebuild and restart via Air
+
+## πŸ› οΈ Development Commands
+
+**Note**: All commands should be run from the project root directory (`arcane/`).
+
+### Environment Management
+```bash
+# Start development environment
+./scripts/development/dev.sh start
+
+# View service status
+./scripts/development/dev.sh status
+
+# Stop all services
+./scripts/development/dev.sh stop
+
+# Restart services (for config changes)
+./scripts/development/dev.sh restart
+
+# Rebuild containers (for dependency changes)
+./scripts/development/dev.sh rebuild
+
+# Clean up everything (nuclear option)
+./scripts/development/dev.sh clean
+```
+
+### Debugging & Logs
+```bash
+# Interactive log selection
+./scripts/development/dev.sh logs
+
+# All services
+./scripts/development/dev.sh logs
+
+# Frontend only (Vite/SvelteKit)
+./scripts/development/dev.sh logs frontend
+
+# Backend only (Go/Air)
+./scripts/development/dev.sh logs backend
+
+# Shell access
+./scripts/development/dev.sh shell frontend
+./scripts/development/dev.sh shell backend
+```
+
+## 🎨 Code Quality
+
+### Automatic Formatting & Linting
+
+Both services include development-time linting and formatting:
+
+- **Frontend**: ESLint + Prettier (configured in VS Code)
+- **Backend**: Go fmt + Go vet (built into Air hot reload)
+
+### Manual Commands
+
+If you need to run checks manually:
+
+```bash
+# Frontend checks
+docker compose -f docker-compose.dev.yml exec frontend pnpm check
+docker compose -f docker-compose.dev.yml exec frontend pnpm format
+
+# Backend checks
+docker compose -f docker-compose.dev.yml exec backend go fmt ./...
+docker compose -f docker-compose.dev.yml exec backend go vet ./...
+```
+
+## πŸ“ Commit Guidelines
+
+We use **Conventional Commits** for clear, semantic commit messages:
+
+```bash
+git commit -m "feat: add user authentication"
+git commit -m "fix: resolve Docker volume mounting issue"
+git commit -m "docs: update development setup guide"
+git commit -m "refactor: simplify API response handling"
+```
+
+**Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+## πŸ”„ Pull Request Process
+
+1. **Keep changes focused** - One feature/fix per PR
+2. **Test your changes** - Ensure both frontend and backend work
+3. **Update documentation** - If you change APIs or add features
+4. **Link issues** - Reference issues with "Closes #123" or "Fixes #456"
+5. **Be responsive** - Address review feedback promptly
+
+### PR Checklist
+
+- [ ] Code builds successfully in development environment
+- [ ] Frontend hot reload works correctly
+- [ ] Backend hot reload works correctly
+- [ ] No linting errors
+- [ ] Commit messages follow conventional format
+- [ ] PR description explains the change and why it's needed
-- Conventional Commits for messages:
+## πŸ› Troubleshooting
- ```bash
- git add .
- git commit -m "feat: add X"
- # or
- git commit -m "fix: resolve Y"
- ```
+### Common Issues
-- Frontend lint/format:
+**Port conflicts:**
+```bash
+# Stop and clean everything (from project root)
+./scripts/development/dev.sh clean
- ```bash
- cd frontend
- pnpm check
- pnpm format
- ```
+# Check for conflicting processes
+lsof -i :3000 # Frontend port
+lsof -i :3552 # Backend port
+```
-- Backend basics:
+**Docker issues:**
+```bash
+# Reset Docker environment (from project root)
+./scripts/development/dev.sh clean
+docker system prune -f
- ```bash
- cd backend
- go fmt ./...
- go vet ./...
- ```
+# Restart development
+./scripts/development/dev.sh start
+```
-## Pull Requests
+**VS Code tasks not working:**
+- Ensure you've opened the project root folder (`arcane/`) in VS Code, not a subfolder or parent directory
+- Install recommended extensions when prompted
+- Restart VS Code if tasks don't appear
+- Verify you're in the correct working directory when running terminal commands
-- Keep changes focused and small when possible.
-- Include context in the PR description and link issues (e.g., β€œCloses #123”).
-- Be ready to iterate based on review feedback.
+### Need Help?
-## Issues & Feedback
+- **Bug Report**: [Create an issue](https://github.com/ofkm/arcane/issues/new?template=bug.yml)
+- **Feature Request**: [Suggest a feature](https://github.com/ofkm/arcane/issues/new?template=feature.yml)
+- **Development Question**: Open a discussion in the repository
-- Bug Report: https://github.com/ofkm/arcane/issues/new?template=bug.yml
-- Feature Request: https://github.com/ofkm/arcane/issues/new?template=feature.yml
+Thank you for contributing to Arcane! Your help makes this project better for everyone. πŸš€
diff --git a/backend/.air.toml b/backend/.air.toml
index c9e6fcdae..e8afd0524 100644
--- a/backend/.air.toml
+++ b/backend/.air.toml
@@ -6,6 +6,34 @@ tmp_dir = ".bin"
cmd = "CGO_ENABLED=1 go build -o ./.bin/arcane ./cmd"
exclude_dir = [".bin", "data"]
stop_on_error = true
+ delay = 1000
+ exclude_regex = ["_test.go"]
+ exclude_unchanged = false
+ follow_symlink = false
+ include_ext = ["go", "tpl", "tmpl", "html"]
+ kill_delay = "0s"
+ log = "build-errors.log"
+ poll = false
+ poll_interval = 0
+ rerun = false
+ rerun_delay = 500
+ send_interrupt = false
+ stop_on_root = false
+
+[color]
+ app = ""
+ build = "yellow"
+ main = "magenta"
+ runner = "green"
+ watcher = "cyan"
+
+[log]
+ main_only = false
+ time = false
[misc]
- clean_on_exit = true
\ No newline at end of file
+ clean_on_exit = false
+
+[screen]
+ clear_on_rebuild = false
+ keep_scroll = true
\ No newline at end of file
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
new file mode 100644
index 000000000..923e125b8
--- /dev/null
+++ b/docker-compose.dev.yml
@@ -0,0 +1,82 @@
+services:
+ # Frontend development service with hot reload
+ frontend:
+ build:
+ context: .
+ dockerfile: docker/Dockerfile.dev
+ target: frontend-dev
+ args:
+ NODE_VERSION: "24"
+ container_name: arcane-frontend-dev
+ ports:
+ - '3000:3000'
+ volumes:
+ # Source code mounting for hot reload
+ - ./frontend:/app/frontend:cached
+ - ./package.json:/app/package.json:ro
+ - ./pnpm-workspace.yaml:/app/pnpm-workspace.yaml:ro
+ - ./pnpm-lock.yaml:/app/pnpm-lock.yaml:ro
+ # Anonymous volumes for node_modules to avoid conflicts
+ - /app/node_modules
+ - /app/frontend/node_modules
+ environment:
+ - NODE_ENV=development
+ - DEV_BACKEND_URL=http://backend:3552
+ depends_on:
+ - backend
+ networks:
+ - arcane-dev
+ restart: unless-stopped
+ healthcheck:
+ test: ['CMD-SHELL', 'curl -f http://localhost:3000 >/dev/null 2>&1 || exit 1']
+ interval: 30s
+ timeout: 10s
+ retries: 3
+ start_period: 40s
+
+ # Backend development service with hot reload
+ backend:
+ build:
+ context: .
+ dockerfile: docker/Dockerfile.dev
+ target: backend-dev
+ args:
+ GO_VERSION: "1.25"
+ container_name: arcane-backend-dev
+ ports:
+ - '3552:3552'
+ volumes:
+ # Source code mounting for hot reload
+ - ./backend:/app:cached
+ - ./backend/.air.toml:/app/.air.toml:ro
+ # Docker socket for container management
+ - /var/run/docker.sock:/var/run/docker.sock
+ # Persistent data storage
+ - arcane-dev-data:/app/data
+ environment:
+ - GIN_MODE=debug
+ - PORT=3552
+ - ENVIRONMENT=development
+ - PUID=1000
+ - PGID=1000
+ - ENCRYPTION_KEY=dev-encryption-key-replace-in-production
+ - JWT_SECRET=dev-jwt-secret-replace-in-production
+ working_dir: /app
+ networks:
+ - arcane-dev
+ restart: unless-stopped
+ healthcheck:
+ test: ['CMD-SHELL', 'curl -fsS http://localhost:3552/api/health >/dev/null || exit 1']
+ interval: 30s
+ timeout: 10s
+ retries: 3
+ start_period: 40s
+
+networks:
+ arcane-dev:
+ driver: bridge
+ name: arcane-dev-network
+
+volumes:
+ arcane-dev-data:
+ name: arcane-dev-data
diff --git a/docker/Dockerfile.dev b/docker/Dockerfile.dev
new file mode 100644
index 000000000..63a662e47
--- /dev/null
+++ b/docker/Dockerfile.dev
@@ -0,0 +1,55 @@
+# Development Dockerfile with hot reload support
+ARG NODE_VERSION="24"
+ARG GO_VERSION="1.25"
+
+# Stage 1: Frontend Development
+FROM node:${NODE_VERSION} AS frontend-dev
+RUN corepack enable
+WORKDIR /app
+
+# Copy package configuration files
+COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
+COPY frontend/package.json ./frontend/package.json
+
+# Install dependencies
+RUN pnpm install --frozen-lockfile
+
+# Set development environment
+ENV NODE_ENV=development
+ENV PORT=3000
+
+# Expose frontend development port
+EXPOSE 3000
+
+# Start frontend development server with hot reload
+CMD ["pnpm", "-C", "frontend", "dev", "--host", "0.0.0.0"]
+
+# Stage 2: Backend Development
+FROM golang:${GO_VERSION}-alpine AS backend-dev
+
+# Install development tools and dependencies
+RUN go install github.com/air-verse/air@latest
+RUN apk add --no-cache git ca-certificates tzdata curl gcc musl-dev
+
+# Set development environment variables
+ENV GIN_MODE=debug
+ENV PORT=3552
+ENV ENVIRONMENT=development
+
+WORKDIR /app
+
+# Copy Go module files
+COPY backend/go.mod backend/go.sum ./
+
+# Download Go dependencies
+RUN go mod download
+
+# Create directories for development
+RUN mkdir -p /app/data && chmod 755 /app/data
+RUN mkdir -p /app/.bin && chmod 755 /app/.bin
+
+# Expose backend development port
+EXPOSE 3552
+
+# Use Air for hot reloading in development
+CMD ["air", "-c", ".air.toml"]
diff --git a/scripts/development/dev.sh b/scripts/development/dev.sh
new file mode 100755
index 000000000..e130ce84c
--- /dev/null
+++ b/scripts/development/dev.sh
@@ -0,0 +1,406 @@
+#!/bin/bash
+
+# Arcane Development Environment Manager
+# This script helps manage the Docker-based development environment with hot reloading
+
+set -euo pipefail
+
+# Configuration
+readonly COMPOSE_FILE="docker-compose.dev.yml"
+readonly PROJECT_NAME="arcane-dev"
+readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+readonly PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+
+# Colors for output
+readonly RED='\033[0;31m'
+readonly GREEN='\033[0;32m'
+readonly YELLOW='\033[1;33m'
+readonly BLUE='\033[0;34m'
+readonly NC='\033[0m' # No Color
+
+# Helper functions
+log_info() {
+ echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+log_success() {
+ echo -e "${GREEN}[SUCCESS]${NC} $1"
+}
+
+log_warning() {
+ echo -e "${YELLOW}[WARNING]${NC} $1"
+}
+
+log_error() {
+ echo -e "${RED}[ERROR]${NC} $1"
+}
+
+install_docker() {
+ local platform arch
+ platform="$(uname -s | tr '[:upper:]' '[:lower:]')"
+ arch="$(uname -m)"
+
+ log_info "Installing Docker using download script..."
+ if ! "${SCRIPT_DIR}/download-docker.sh" "$platform" "$arch" "28.4.0"; then
+ log_error "Failed to install Docker"
+ return 1
+ fi
+
+ # Add to PATH for current session
+ export PATH="${PROJECT_ROOT}/dist:$PATH"
+ log_success "Docker installed successfully"
+ return 0
+}
+
+install_compose() {
+ local dest="${PROJECT_ROOT}/dist/docker-compose"
+
+ log_info "Installing Docker Compose using download script..."
+ if ! "${SCRIPT_DIR}/download-compose.sh" "2.39.2" "$dest"; then
+ log_error "Failed to install Docker Compose"
+ return 1
+ fi
+
+ # Add to PATH for current session
+ export PATH="${PROJECT_ROOT}/dist:$PATH"
+ log_success "Docker Compose installed successfully"
+ return 0
+}
+
+offer_installation() {
+ local missing_tools=()
+ local install_docker=false
+ local install_compose=false
+
+ # Check what's missing
+ if ! command -v docker &> /dev/null; then
+ missing_tools+=("Docker")
+ install_docker=true
+ fi
+
+ if ! docker compose version &> /dev/null 2>&1; then
+ missing_tools+=("Docker Compose")
+ install_compose=true
+ fi
+
+ if [[ ${#missing_tools[@]} -eq 0 ]]; then
+ return 0
+ fi
+
+ log_warning "Missing required tools: ${missing_tools[*]}"
+ echo
+ log_info "We can automatically install these tools for you using the project's download scripts."
+ log_info "The tools will be installed locally in the project directory (${PROJECT_ROOT}/dist/)"
+ echo
+
+ read -p "Would you like to install the missing tools automatically? (y/N): " -n 1 -r
+ echo
+
+ if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+ log_info "Installation cancelled."
+ log_info "Please install Docker and Docker Compose manually, then run this script again."
+ return 1
+ fi
+
+ # Install missing tools
+ if [[ $install_docker == true ]]; then
+ if ! install_docker; then
+ return 1
+ fi
+ fi
+
+ if [[ $install_compose == true ]]; then
+ if ! install_compose; then
+ return 1
+ fi
+ fi
+
+ log_success "All required tools installed successfully!"
+ echo
+ return 0
+}
+
+check_requirements() {
+ local docker_available=true
+ local daemon_running=true
+ local compose_available=true
+
+ # Check if Docker is available
+ if ! command -v docker &> /dev/null; then
+ docker_available=false
+ fi
+
+ # Check if Docker daemon is running (only if Docker is available)
+ if [[ $docker_available == true ]] && ! docker info &> /dev/null; then
+ daemon_running=false
+ fi
+
+ # Check if Docker Compose is available
+ if ! docker compose version &> /dev/null; then
+ compose_available=false
+ fi
+
+ # If Docker or Compose are missing, offer installation
+ if [[ $docker_available == false ]] || [[ $compose_available == false ]]; then
+ if ! offer_installation; then
+ exit 1
+ fi
+
+ # Re-check after installation
+ if ! command -v docker &> /dev/null; then
+ log_error "Docker installation failed or is not in PATH"
+ exit 1
+ fi
+
+ if ! docker compose version &> /dev/null; then
+ log_error "Docker Compose installation failed or is not in PATH"
+ exit 1
+ fi
+ fi
+
+ # Check Docker daemon (after ensuring Docker is installed)
+ if ! docker info &> /dev/null; then
+ log_error "Docker daemon is not running"
+ log_error "Please start Docker Desktop or the Docker daemon and try again"
+ exit 1
+ fi
+
+ log_info "All requirements satisfied βœ“"
+}
+
+ensure_project_root() {
+ if [[ ! -f "${PROJECT_ROOT}/${COMPOSE_FILE}" ]]; then
+ log_error "Could not find ${COMPOSE_FILE} in project root"
+ log_error "Please run this script from the project root directory or ensure the compose file exists"
+ exit 1
+ fi
+
+ # Change to project root to ensure relative paths work correctly
+ cd "${PROJECT_ROOT}"
+}
+
+show_status() {
+ log_info "Development environment status:"
+ docker compose -f $COMPOSE_FILE -p $PROJECT_NAME ps
+}
+
+show_logs() {
+ local service="${1:-}"
+
+ if [[ -z "$service" ]]; then
+ log_info "Showing logs for all services..."
+ docker compose -f "${COMPOSE_FILE}" -p "${PROJECT_NAME}" logs -f
+ else
+ # Validate service name
+ if [[ ! "$service" =~ ^(frontend|backend)$ ]]; then
+ log_error "Invalid service name: $service"
+ log_error "Valid services: frontend, backend"
+ exit 1
+ fi
+
+ log_info "Showing logs for service: $service"
+ docker compose -f "${COMPOSE_FILE}" -p "${PROJECT_NAME}" logs -f "$service"
+ fi
+}
+
+create_env_file() {
+ local env_file=".env"
+
+ if [[ -f "$env_file" ]]; then
+ return 0
+ fi
+
+ log_warning ".env file not found, creating basic development configuration..."
+ cat > "$env_file" << 'EOF'
+# Development Environment Configuration
+# WARNING: These are development-only values, never use in production!
+
+ENCRYPTION_KEY=dev-encryption-key-replace-in-production-must-be-32-chars
+JWT_SECRET=dev-jwt-secret-replace-in-production-must-be-long-enough
+DATABASE_TYPE=sqlite
+DATABASE_PATH=/app/data/arcane.db
+GIN_MODE=debug
+ENVIRONMENT=development
+EOF
+ log_success "Created .env file with development defaults"
+}
+
+start_dev() {
+ log_info "Starting Arcane development environment..."
+
+ create_env_file
+
+ if ! docker compose -f "${COMPOSE_FILE}" -p "${PROJECT_NAME}" up -d --build; then
+ log_error "Failed to start development environment"
+ exit 1
+ fi
+
+ log_success "Development environment started!"
+ log_info "Frontend: http://localhost:3000"
+ log_info "Backend: http://localhost:3552"
+ log_info ""
+ log_info "Use './scripts/development/dev.sh logs' to view logs"
+ log_info "Use './scripts/development/dev.sh logs frontend' or './scripts/development/dev.sh logs backend' for specific service logs"
+}
+
+stop_dev() {
+ log_info "Stopping Arcane development environment..."
+ if ! docker compose -f "${COMPOSE_FILE}" -p "${PROJECT_NAME}" down; then
+ log_error "Failed to stop development environment"
+ exit 1
+ fi
+ log_success "Development environment stopped!"
+}
+
+restart_dev() {
+ log_info "Restarting Arcane development environment..."
+ if ! docker compose -f "${COMPOSE_FILE}" -p "${PROJECT_NAME}" restart; then
+ log_error "Failed to restart development environment"
+ exit 1
+ fi
+ log_success "Development environment restarted!"
+}
+
+clean_dev() {
+ log_warning "This will remove all containers, networks, and volumes for the development environment."
+ read -p "Are you sure? (y/N): " -n 1 -r
+ echo
+ if [[ $REPLY =~ ^[Yy]$ ]]; then
+ log_info "Cleaning up development environment..."
+ if ! docker compose -f "${COMPOSE_FILE}" -p "${PROJECT_NAME}" down -v --remove-orphans; then
+ log_error "Failed to remove containers and volumes"
+ exit 1
+ fi
+
+ if ! docker system prune -f; then
+ log_warning "Failed to prune Docker system, but containers were removed"
+ fi
+
+ log_success "Development environment cleaned!"
+ else
+ log_info "Cleanup cancelled."
+ fi
+}
+
+rebuild_dev() {
+ log_info "Rebuilding development environment..."
+
+ if ! docker compose -f "${COMPOSE_FILE}" -p "${PROJECT_NAME}" down; then
+ log_error "Failed to stop containers"
+ exit 1
+ fi
+
+ if ! docker compose -f "${COMPOSE_FILE}" -p "${PROJECT_NAME}" build --no-cache; then
+ log_error "Failed to rebuild containers"
+ exit 1
+ fi
+
+ if ! docker compose -f "${COMPOSE_FILE}" -p "${PROJECT_NAME}" up -d; then
+ log_error "Failed to start containers"
+ exit 1
+ fi
+
+ log_success "Development environment rebuilt and started!"
+}
+
+shell_into() {
+ local service="${1:-}"
+
+ if [[ -z "$service" ]]; then
+ log_error "Please specify a service: frontend or backend"
+ exit 1
+ fi
+
+ # Validate service name
+ if [[ ! "$service" =~ ^(frontend|backend)$ ]]; then
+ log_error "Invalid service name: $service"
+ log_error "Valid services: frontend, backend"
+ exit 1
+ fi
+
+ log_info "Opening shell in $service container..."
+ if ! docker compose -f "${COMPOSE_FILE}" -p "${PROJECT_NAME}" exec "$service" /bin/sh; then
+ log_error "Failed to open shell in $service container"
+ log_error "Make sure the container is running: ./scripts/development/dev.sh status"
+ exit 1
+ fi
+}
+
+show_help() {
+ echo "Arcane Development Environment Manager"
+ echo
+ echo "Usage: $0 [COMMAND]"
+ echo
+ echo "Commands:"
+ echo " start Start the development environment"
+ echo " stop Stop the development environment"
+ echo " restart Restart the development environment"
+ echo " status Show status of all services"
+ echo " logs Show logs (optionally specify service: frontend, backend)"
+ echo " clean Remove all containers, networks, and volumes"
+ echo " rebuild Rebuild and restart the development environment"
+ echo " shell Open shell in a service container (specify: frontend or backend)"
+ echo " help Show this help message"
+ echo
+ echo "Features:"
+ echo " β€’ Automatic Docker/Compose installation if missing (using project scripts)"
+ echo " β€’ Hot reload for both frontend (Vite) and backend (Air)"
+ echo " β€’ Interactive log viewing with service selection"
+ echo " β€’ Automatic project root detection"
+ echo
+ echo "Examples:"
+ echo " $0 start"
+ echo " $0 logs backend"
+ echo " $0 shell frontend"
+ echo
+ echo "Note: If Docker or Docker Compose are not installed, you'll be prompted"
+ echo " to install them automatically using the project's download scripts."
+}
+
+# Main script logic
+main() {
+ # Check requirements and ensure we're in the right directory
+ check_requirements
+ ensure_project_root
+
+ local command="${1:-help}"
+
+ case "$command" in
+ start)
+ start_dev
+ ;;
+ stop)
+ stop_dev
+ ;;
+ restart)
+ restart_dev
+ ;;
+ status)
+ show_status
+ ;;
+ logs)
+ show_logs "${2:-}"
+ ;;
+ clean)
+ clean_dev
+ ;;
+ rebuild)
+ rebuild_dev
+ ;;
+ shell)
+ shell_into "${2:-}"
+ ;;
+ help|--help|-h)
+ show_help
+ ;;
+ *)
+ log_error "Unknown command: $command"
+ echo
+ show_help
+ exit 1
+ ;;
+ esac
+}
+
+# Run main function with all arguments
+main "$@"
\ No newline at end of file