StackMark

Docker Stack Management Made Simple

Beautiful CLI • Zero Port Conflicts • Full Control

Manage multiple Docker Compose projects effortlessly. Automatic port allocation, interactive dashboard, and smart project templates—all from your terminal.

Website • Quick Start • Features • Commands • Templates

---

⚡ Quick Start

# Install globally
npm install -g @grazulex/stackmark

# Register your existing project
cd ~/Dev/my-project
stackmark add

# Start the stack
stackmark start

# Open interactive dashboard
stackmark dash

That's it! StackMark handles port conflicts automatically and provides a unified interface for all your Docker stacks.

---

✨ Features

🔌 Automatic Port Allocation No more port conflicts! StackMark automatically assigns unique ports to each stack starting from 9000.	📊 Interactive Dashboard Real-time TUI with auto-refresh showing all your stacks, their status, and running containers.
🎯 Smart Auto-Detection Run commands from any project directory—StackMark automatically detects which stack you're working with.	🏗️ Project Scaffolding Generate docker-compose.yml with interactive templates for Laravel, Symfony, Node.js, WordPress, and more.
🌐 Hosts Management Sync local domains (myapp.local) to /etc/hosts with a single command.	🎨 Beautiful Terminal UI Colorful output, status indicators, and a modern CLI experience.

---

🖥️ Commands

stackmark init

Generate a new docker-compose.yml with interactive prompts.

cd ~/Dev/new-project
stackmark init

Select from templates (Laravel, Symfony, Node.js, etc.) or build a custom stack.

stackmark add [name]

Register a stack in StackMark.

stackmark add                           # Use current directory
stackmark add myapp                     # With custom name
stackmark add myapp --path ~/Dev/myapp  # With specific path
stackmark add myapp --domain myapp.local # With local domain

stackmark start [name]

Start a stack with automatic port management.

stackmark start                         # Auto-detect from current dir
stackmark start myapp                   # Start specific stack
stackmark start --no-override           # Use original ports

stackmark stop [name]

Stop a running stack.

stackmark stop                          # Auto-detect
stackmark stop myapp                    # Stop specific stack

stackmark status [name]

Show detailed stack status with container info.

stackmark status                        # Current directory stack
stackmark status myapp                  # Specific stack
stackmark status --all                  # All stacks

Example output:

🐳 Stack Status

  ● myapp running
    → http://localhost:9003
    Path: /home/user/Dev/myapp
    Other: db:9004, redis:9005
    └─ myapp_app: Up 5 minutes
    └─ myapp_db: Up 5 minutes
    └─ myapp_nginx: Up 5 minutes

stackmark list

List all registered stacks with their status.

stackmark list
stackmark ls

Example output:

📦 Stacks

  ● myapp
    → http://localhost:9003
    /home/user/Dev/myapp

  ○ other-project
    → http://localhost:9007
    /home/user/Dev/other-project

stackmark dashboard

Interactive dashboard with real-time updates.

stackmark dashboard
stackmark dash

Features:

• Auto-refresh every 2 seconds
• Running/stopped/partial status indicators
• Press q to quit

stackmark open [name]

Open the stack's main URL in your browser.

stackmark open                          # Auto-detect
stackmark open myapp                    # Specific stack

stackmark restart [name]

Restart a stack.

stackmark restart                       # Auto-detect
stackmark restart myapp                 # Specific stack
stackmark restart --no-override         # With original ports

stackmark logs [name]

View stack logs.

stackmark logs                          # Auto-detect
stackmark logs myapp                    # Specific stack
stackmark logs -f                       # Follow mode

stackmark remove <name>

Remove a registered stack.

stackmark remove myapp
stackmark rm myapp

stackmark hosts sync

Sync local domains to /etc/hosts.

sudo stackmark hosts sync

---

🏗️ Templates

Generate complete Docker Compose configurations with stackmark init:

Template	Stack
Laravel	PHP + Nginx + MySQL + Redis + Mailpit
Symfony	PHP + Nginx + PostgreSQL + Redis + Mailpit
Node.js	Node + PostgreSQL + Redis
WordPress	PHP + Nginx + MariaDB + Redis + Mailpit
API	PHP + Nginx + PostgreSQL + Redis
Custom	Choose your own services

Available Services

Category	Services
Runtime	PHP (8.3, 8.2, 8.1), Node.js (22, 20, 18)
Webserver	Nginx
Database	MySQL, MariaDB, PostgreSQL
Cache	Redis, Memcached
Tools	Mailpit, MinIO (S3), phpMyAdmin

---

🔌 Port Management

How It Works

1. When you stackmark add a project, StackMark scans docker-compose.yml for port mappings
2. It allocates unique external ports starting from 9000
3. When you stackmark start, it creates a temporary override file
4. Your original docker-compose.yml is never modified

Example

Original docker-compose.yml:

services:
  nginx:
    ports:
      - "80:80"
  db:
    ports:
      - "3306:3306"

StackMark allocates:

nginx: localhost:9003 → container:80
db:    localhost:9004 → container:3306

Using Original Ports

Need to test with original ports? No problem:

stackmark start --no-override

---

⚙️ Configuration

Configuration is stored in ~/.stackmark/config.yml:

stacks:
  myapp:
    path: /home/user/Dev/myapp
    domains:
      - myapp.local
    portMappings:
      - service: nginx
        internal: 80
        external: 9003
      - service: db
        internal: 3306
        external: 9004
nextPort: 9010

---

🎯 Auto-Detection

Most commands auto-detect the stack when run from a project directory:

cd ~/Dev/myapp
stackmark start      # Starts myapp
stackmark logs -f    # Shows myapp logs
stackmark status     # Shows myapp status

Override auto-detection when needed:

stackmark status --all    # Show all stacks
stackmark start other     # Start a different stack

---

🚀 Installation

npm (Recommended)

npm install -g @grazulex/stackmark

npx (No install)

npx @grazulex/stackmark dash

Verify Installation

stackmark --version

---

📊 Comparison

Feature	StackMark	Docker Compose	Dockstation	Portainer
CLI-first	✅	✅	❌	❌
Auto Port Allocation	✅	❌	❌	❌
Project Templates	✅	❌	❌	⚠️
Multi-stack Dashboard	✅	❌	✅	✅
Zero Config	✅	⚠️	❌	❌
Auto-detection	✅	❌	❌	❌
Hosts Sync	✅	❌	❌	❌

---

🛠️ Troubleshooting

Port Already in Use

Check which stacks are using ports:

stackmark status --all

Or use original ports:

stackmark start --no-override

/etc/hosts Permission Denied

The hosts sync command requires sudo:

sudo stackmark hosts sync

Stack Not Detected

Make sure you're in the project root (where docker-compose.yml is located) or specify the stack name.

---

🤝 Contributing

Contributions are welcome! Whether it's:

• 🐛 Bug reports
• ✨ Feature requests
• 📝 Documentation improvements
• 🔧 Code contributions

---

📄 License

MIT © Grazulex

---

🌐 Website • 📦 npm • 🐛 Issues • 💬 Discussions

---

Built with ❤️ for developers who juggle multiple Docker projects

Star this repo if StackMark simplifies your workflow! ⭐