A collection of universal Just command modules for container management, database operations, and development workflows. Built with Just's modern module system and designed for maximum reusability.

🚀 Features

🎯 Module-Based Architecture: Clean separation using Just's native module system
🎨 Modern Just Features: Built-in colors, groups, and confirm attributes
📦 Optional Modules: Include only what you need
🐳 Universal Container Support: Works with Docker and Podman
🗄️ Database Operations: PostgreSQL and MySQL support
🔒 Built-in Safety: Confirmation prompts for destructive operations
🏗️ Zero Dependencies: Pure Just recipes with automatic runtime detection

📋 Requirements

Just Command Runner

This library requires Just 1.31.0 or later for module support and modern features.

Installation on Ubuntu 24.04 LTS

Method 1: Snap (Recommended for latest version)

sudo snap install just --classic

Method 2: Manual Installation from GitHub

# Get the latest version
JUST_VERSION=$(curl -s "https://api.github.com/repos/casey/just/releases/latest" | grep -Po '"tag_name": "\K[0-9.]+')

# Download and install
wget -qO just.tar.gz "https://github.com/casey/just/releases/latest/download/just-${JUST_VERSION}-x86_64-unknown-linux-musl.tar.gz"
tar -xzf just.tar.gz
sudo mv just /usr/local/bin/
chmod +x /usr/local/bin/just

# Verify installation
just --version

Other Platforms

macOS: brew install just
Windows: choco install just or scoop install just
Other Linux: See official installation guide

Other Requirements

Docker or Podman
Git

🏗️ Module Architecture

just-commons/
├── README.md              # This documentation
├── justfile               # Main file with module declarations and help
├── core.just              # Shared utilities (imported)
├── postgres/
│   └── mod.just          # PostgreSQL module
├── mysql/
│   └── mod.just          # MySQL module
├── volumes/
│   └── mod.just          # Volume management module
├── container/
│   └── mod.just          # Container operations module
├── registry/
│   └── mod.just          # Registry authentication module
└── images/
    └── mod.just          # Image operations module

🔧 Usage

Add as Git Submodule

git submodule add git@github.com:shadoll/just-commons.git just-commons
cd just-commons
git checkout main

Import in Your Justfile

# Import core utilities (required)
import 'just-commons/core.just'

# Declare optional modules (use only what you need)
mod? postgres 'just-commons/postgres'
mod? mysql 'just-commons/mysql'
mod? volumes 'just-commons/volumes'
mod? container 'just-commons/container'
mod? registry 'just-commons/registry'
mod? images 'just-commons/images'

Example Project Justfile

# My Project Justfile
import 'just-commons/core.just'

# Only include modules I need
mod? container 'just-commons/container'
mod? postgres 'just-commons/postgres'
mod? volumes 'just-commons/volumes'

# Project-specific commands
[group('project')]
setup:
    just container start
    just postgres sql "CREATE DATABASE myapp;"

[group('project')]
teardown:
    just volumes clean-all

📚 Available Modules

🐳 Container Module (`container`)

Universal container operations with optional compose file support

just container start [service] [compose-file]     # Start services
just container stop [service] [compose-file]      # Stop services
just container restart [service] [compose-file]   # Restart services
just container status [service] [compose-file]    # Show service status
just container logs [service] [compose-file]      # View service logs
just container shell <service> [compose-file]     # Open shell in container
just container exec <service> <cmd> [compose-file] # Execute command

🗄️ Database Modules

PostgreSQL Module (`postgres`)

just postgres sql <query> [service] [compose-file]        # Execute SQL query
just postgres check [service] [compose-file]              # Check connection
just postgres list-databases [service] [compose-file]     # List databases
just postgres list-users [service] [compose-file]         # List users
just postgres create-database <name> [service]            # Create database
just postgres drop-database <name> [service]              # Drop database (with confirmation)
just postgres shell [service] [compose-file]              # Interactive shell
just postgres restore <backup> [service] [compose-file]   # Restore from backup (with confirmation)

MySQL Module (`mysql`)

just mysql sql <query> [service] [compose-file]           # Execute SQL query
just mysql check [service] [compose-file]                 # Check connection
just mysql list-databases [service] [compose-file]        # List databases
just mysql list-users [service] [compose-file]            # List users
just mysql create-database <name> [service]               # Create database
just mysql drop-database <name> [service]                 # Drop database (with confirmation)
just mysql create-user <username> <password> [service]    # Create user
just mysql grant-privileges <database> <username> [service] # Grant privileges
just mysql shell [service] [compose-file]                 # Interactive shell
just mysql restore <backup> <database> [service]          # Restore from backup (with confirmation)

💾 Volume Module (`volumes`)

Safe volume management with built-in confirmations

just volumes clean-all [compose-file]                     # Remove all compose volumes (with confirmation)
just volumes remove <volume-name>                         # Remove specific volume (with confirmation)
just volumes remove-pattern <pattern>                     # Remove volumes matching pattern (with confirmation)
just volumes list [pattern]                               # List volumes (optionally filtered)

🐋 Images Module (`images`)

Universal image operations with intelligent auto-discovery and cross-platform builds

just images build [project] [tag]                         # Build project image (auto-discovers project and Containerfile)
just images push [project] [tag]                          # Push image to registry (auto-discovers project)
just images pull [project] [tag]                          # Pull image from registry (auto-discovers project)
just images tag <project> <new-tag>                       # Tag existing image
just images info [project] [tag]                          # Show image information (auto-discovers project)
just images clean [project]                               # Remove project images (auto-discovers project, with confirmation)
just images build-all                                     # Build all projects with Containerfiles (uses discovery logic)

Auto-Discovery Features:

Project Detection: Automatically uses directory basename when project not specified
Containerfile Discovery: Finds Containerfile/Dockerfile in current directory or ./docker/ folder
Cross-Platform Builds: Handles macOS compatibility for Linux containers automatically
Smart Parameter Parsing: just images push latest correctly interprets "latest" as tag, not project
Unified Discovery Logic: Consistent behavior whether using auto-discovery or explicit project directories

🔐 Registry Module (`registry`)

Container registry authentication management

just registry login                                       # Login to container registry
just registry logout                                      # Logout from registry
just registry check                                       # Check authentication status

🔧 Core Utilities

Shared functions, auto-discovery, and environment checking

just env-check                                           # Check container runtime availability
just _detect_runtime                                     # Internal: Detect Docker/Podman
just _detect_compose                                     # Internal: Detect compose command
just _discover_project                                   # Internal: Auto-discover project name from directory
just _discover_containerfile_in [dir]                   # Internal: Discover Containerfile/Dockerfile in directory
just _discover_containerfile                            # Internal: Discover Containerfile/Dockerfile in current directory

Auto-Discovery Functions:

_discover_project: Returns $(basename $(pwd)) - the current directory name as project name
_discover_containerfile_in: Searches for Containerfile/Dockerfile in specified directory, also checks ./docker/ subfolder when searching current directory
_discover_containerfile: Convenience wrapper for current directory discovery

These functions enable consistent auto-discovery behavior across all modules.

🎨 Modern Just Features

Built-in Colors

Uses Just's native color constants instead of custom ANSI codes:

{{RED}}, {{GREEN}}, {{BLUE}}, {{YELLOW}}
{{BOLD}}, {{NORMAL}}

Command Groups

All commands are organized with [group('name')] attributes:

container - Container operations
database - Database operations
volumes - Volume management
images - Image operations
registry - Registry operations
environment - Environment checking

Safety Confirmations

Destructive operations use [confirm] attribute:

Volume removal operations
Database dropping
Image cleaning
Backup restoration

🌍 Environment Configuration

Registry Configuration

Authentication vs Registry Namespace

The system separates authentication credentials from registry image paths, allowing you to authenticate with your personal account while pushing to organization namespaces.

# .env file - Registry settings
GITHUB_USERNAME=your-auth-username    # For authentication (just registry login)
GITHUB_TOKEN=ghp_your-token          # For authentication
REGISTRY_NAMESPACE=org-or-username   # For image paths (ghcr.io/NAMESPACE/project:tag)
REGISTRY=ghcr.io                     # Registry URL (optional, defaults to ghcr.io)

Configuration Hierarchy:

Registry Namespace (for image paths):
- REGISTRY_NAMESPACE (if set) - highest priority
- GITHUB_USERNAME (fallback) - backward compatibility
- Error if neither is set
Registry URL:
- REGISTRY (if set) - custom registry
- ghcr.io (default) - GitHub Container Registry

Examples:

# Organization setup
GITHUB_USERNAME=john-doe              # Personal auth
REGISTRY_NAMESPACE=my-company         # Company namespace
# Result: ghcr.io/my-company/project:tag

# Personal setup
GITHUB_USERNAME=john-doe              # Personal auth and namespace
# Result: ghcr.io/john-doe/project:tag

# Custom registry
REGISTRY=docker.io
REGISTRY_NAMESPACE=myorg
# Result: docker.io/myorg/project:tag

Optional Overrides

# Auto-detected, but can be explicitly set
CONTAINER_RUNTIME=docker  # or 'podman'
COMPOSE_CMD="docker compose"  # or 'podman-compose'

📖 Usage Examples

Development Workflow

# Environment setup
just env-check                           # Verify container runtime
just registry login                      # Authenticate with registry

# Container management
just container start postgres            # Start PostgreSQL service
just container logs postgres             # View logs
just postgres check                      # Test database connection

# Development operations (with auto-discovery)
just postgres sql "CREATE DATABASE myapp;" # Create development database
just images build                        # Build application image (auto-discovers project and Containerfile)
just images push dev                     # Push development version (auto-discovers project, "dev" as tag)
just images push                         # Push with auto-generated commit tag

Production Deployment

# Pull latest images (with auto-discovery)
just images pull latest                  # Pull latest version (auto-discovers project)
just images pull postgres 15            # Pull specific PostgreSQL version

# Database operations
just postgres restore latest-backup.sql  # Restore from backup (with confirmation)
just postgres sql "ANALYZE;"             # Optimize database

# Volume management
just volumes list "production_*"         # List production volumes
just volumes clean-all compose.prod.yml  # Clean up old volumes (with confirmation)

# Build and deployment
just images build-all                    # Build all projects with Containerfiles (auto-discovery)
just images info                         # Show image information (auto-discovers project)

Multi-Database Setup

# PostgreSQL setup
just postgres create-database main_db
just postgres sql "CREATE USER app_user WITH PASSWORD 'secret';" postgres

# MySQL setup
just mysql create-database cache_db
just mysql create-user cache_user secret123 mysql
just mysql grant-privileges cache_db cache_user mysql

🆕 Migration from Version 1.x

Breaking Changes in Version 2.0:

Command Structure

Old: just postgres-sql "query"
New: just postgres sql "query"

Module Declaration

Old: import 'just-commons/postgres.just'
New: mod postgres 'just-commons/postgres'

Color Variables

Old: Custom ${GREEN}, ${RED} variables
New: Built-in {{GREEN}}, {{RED}} constants

Migration Steps

Update to Just 1.31.0+
Replace import statements with mod declarations
Update command calls to use module syntax
Remove custom color variable definitions

🤝 Contributing

Fork the repository
Create feature branch: git checkout -b feature/new-module
Follow existing module patterns
Use modern Just features (groups, confirm, built-in colors)
Test across different environments
Update documentation
Submit pull request

📝 License

MIT License - see LICENSE file for details.

🔗 Links

Just Commons v2.0 - Modern, modular, and maintainable command automation for container-based projects.

README.md

Just Commons - Universal Command Library