KyanJeuring/dstack: DStack is a small Bash tool that lets you manage multiple Docker Compose projects from anywhere in the terminal.

Docker Compose stack management

DStack is a small Bash tool that lets you manage multiple Docker Compose projects from anywhere in the terminal.

No more constantly changing directories just to run docker compose up or down.

Think of it as Docker Desktop-style convenience for Docker Compose, without a GUI.

DStack is for developers and operators who:

• Run multiple Docker Compose projects
• Work on servers, over SSH, or in homelabs
• Forget where compose files live
• Are tired of cd + docker compose loops
• Prefer small, inspectable shell tools over GUIs

• Run Docker Compose commands from any directory
• Named stacks (dcompose myproject, ddown website, etc.)
• Auto‑discovery of projects in common directories
• Register Compose projects from any path
• Optional active stack context (dstack )
• Clean, UX‑focused error messages
• No dependencies beyond Docker, Bash, and standard POSIX tools
• Server and SSH friendly

DStack is fully supported on Linux distributions.

DStack is available on Windows via WSL or Git Bash.

DStack is available on macOS.

curl -fsSL https://kyanjeuring.com/scripts/install-dstack | bash

curl -fsSL https://kyanjeuring.com/scripts/install-dstack | DSTACK_VERSION=vx.y.z bash

This will:

• Install dstack into ~/.local/share/dstack
• Automatically source it in your shell (.bashrc / .zshrc)

Restart your shell or run:

source ~/.bashrc   # or ~/.zshrc

If you prefer not to use an installer script or pipe remote code into your shell, you can clone the repository directly:

git clone https://github.com/kyanjeuring/dstack.git ~/.local/share/dstack
chmod +x ~/.local/share/dstack/dstack.sh

Then source it into your shell config:

echo 'source ~/.local/share/dstack/dstack.sh' >> ~/.bashrc
# or ~/.zshrc

# list stacks (auto-discovered + registered)
dstack

# compose and start a stack from anywhere
dcompose myproject

# follow logs without cd'ing
dlogs myproject

This shows:

• Registered stacks (explicitly added)
• Auto‑discovered stacks (common project directories)

dcompose myproject
ddown website
dlogs backend

No cd. No guessing where the project lives.

dcompose is a thin wrapper around Docker Compose that automatically resolves the correct Compose context.

It behaves like docker compose, but lets you run commands from anywhere by resolving:

1. An explicit stack name
2. The active stack (dstack )
3. The current directory

When no arguments are provided, dcompose runs:

docker compose [stack] up -d --build --remove-orphans

This provides a fast, consistent “bring everything up” experience.

Full Docker Compose access
Any arguments passed to dcompose are forwarded directly to Docker Compose.

Examples:

dcompose up -d
dcompose mystack restart
dcompose down -v

This allows advanced workflows without limiting Docker Compose functionality.

DStack also provides a set of convenience commands (ddown, dlogs, dexec, etc.) that wrap common Docker Compose operations with safer defaults and clearer intent.

(Plus many more helpers for logs, rebuilds, cleanup, networking.)

All commands can also be run within a project without specifying the current stack name.

Example:

cd /path/to/project
dcompose
dlogs

DStack automatically discovers Docker Compose projects in common development and server locations, so you don’t have to manually register every stack

By default, DStack scans:

• ~/projects
• ~/src
• ~/code
• /opt/services
• C:/Users//projects (Windows / Git Bash)
• C:/Users//src
• C:/Users//code

Any directory up to one level deep that contains a supported Docker Compose file is treated as a stack
(for example media/jellyfin/).

Supported filenames:

• docker-compose.yml
• docker-compose.yaml
• compose.yml
• compose.yaml

These locations were chosen because they are widely used across Linux, macOS, and WSL environments

Discovery is intentionally limited to one level of nesting to keep behavior fast and predictable.

You can register any directory containing a supported Docker Compose file:

Outside a project

dstack add myproject /path/to/project

Inside a project:

cd /path/to/project
dstack add myproject .

After that:

dcompose myproject
dlogs myproject

This is especially useful for:

• Monorepos
• External drives
• Non‑standard directory layouts

When you run a command, dstack resolves the Compose context in this order:

1. Explicit stack name (dcompose myproject)
2. Active stack (dstack myproject)
3. Local Docker Compose file in the current directory

DStack will use the first supported Compose file it finds, in a deterministic order.

If no context is found, dstack tells you exactly what to do.

DStack supports the standard Docker Compose filenames:

• docker-compose.yml
• docker-compose.yaml
• compose.yml
• compose.yaml

When multiple files are present, DStack selects the first matching file in a fixed order to ensure predictable behavior.

DStack does not automatically combine multiple Compose files.
If you rely on overrides (for example docker-compose.override.yml), manage those explicitly via Docker Compose itself.

By default, DStack looks for the standard Docker Compose filenames mentioned above.

Advanced users can override this behavior by setting the DSTACK_COMPOSE_FILES environment variable.

Example:

export DSTACK_COMPOSE_FILES="docker-compose.yml compose.yml"

This allows full control over which Compose files DStack considers during stack resolution.

By default, DStack auto-discovers Docker Compose projects in a small set of common directories, such as:

• ~/projects
• C:/Users//projects (Windows / Git Bash)

Advanced users can override the discovery locations without editing the script by setting the DSTACK_BASES environment variable.

Example:

Add this to your shell config (.bashrc, .zshrc, etc.) to make it permanent and reload the shell:

export DSTACK_BASES="/your/custom/path1 /your/custom/path2"

DStack will then use only these paths for auto-discovery.

You can edit the discovery paths directly in the script, but this is discouraged, as it makes updating DStack harder and can lead to merge conflicts.

If you do edit the script, restart your shell or reload your configuration afterward.

This approach keeps DStack simple while still giving power users full control over their environment.

Updating DStack follows the same method used for installation.

• If you installed via the installer, re-run the installer.
• If you installed via git clone, pull the latest changes.
• If you installed manually, repeat the manual install steps.

After updating, restart your shell or reload your config if needed.

rm -rf ~/.local/share/dstack

Then remove the dstack source line from your shell config.

Contributions are welcome!

Please read CONTRIBUTING.md before submitting a PR.

If you found this project useful and would like to support my work:

https://buymeacoffee.com/kyanjeuring

MIT License