Essex Boilerplate for Docker Based Projects

A Docker project template generator that helps create consistent and well-structured Docker projects.

Features

• Generate Docker projects from templates
• Consistent project structure with best practices
• Makefile-driven workflow
• OCI-compliant labels
• Templates using Tera (Jinja2-like syntax)
• Shell completion support (bash, zsh)

Installation

Quick Install (Linux and macOS)

curl -fsSL -o essex-install.sh https://github.com/utensils/essex/releases/latest/download/download_cli.sh && bash essex-install.sh

This script will:

• Detect your OS and architecture
• Download the appropriate binary
• Install it to ~/.local/bin
• Provide instructions for adding to your PATH

The installer supports:

• macOS (Apple Silicon and Intel)
• Linux (x86_64 and ARM64)

Note: You may need to add ~/.local/bin to your PATH if you haven't already:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc  # or restart your terminal

From Source

cargo install --path .

Shell Completion

Essex supports command-line completion for bash and zsh shells. You can enable it by following these steps:

Bash

1. Generate and install the completion script:

# For current user
mkdir -p ~/.local/share/bash-completion/completions
essex completion bash > ~/.local/share/bash-completion/completions/essex.bash

# Or for system-wide installation (requires sudo)
sudo essex completion bash > /usr/share/bash-completion/completions/essex

2. Add to your ~/.bashrc:

source ~/.local/share/bash-completion/completions/essex.bash

3. Reload your shell or source the file:

source ~/.bashrc

Zsh

1. Create the completion directory and generate the script:

mkdir -p ~/.zfunc
essex completion zsh > ~/.zfunc/_essex

2. Add to your ~/.zshrc:

fpath=(~/.zfunc $fpath)
autoload -Uz compinit
compinit

3. Reload your shell or source the file:

source ~/.zshrc

Testing Completion

After installation, you can test the completion by typing:

essex <TAB>           # Shows available commands (list, new, completion, help)
essex new <TAB>       # Shows available templates
essex completion <TAB> # Shows supported shells (bash, zsh)

Usage

# List available templates
essex list

# Create a new project
essex new basic namespace/project-name --username your-username --vendor "Your Company"

# Generate shell completion
essex completion bash  # For bash
essex completion zsh   # For zsh

Template Structure

The basic template includes:

• Dockerfile with best practices
• Makefile for common Docker operations
• README.md
• Entrypoint script
• OCI-compliant labels

Project Structure

project-name/
├── Dockerfile
├── Makefile
├── README.md
└── runtime-assets/
    └── usr/
        └── local/
            └── bin/
                └── entrypoint.sh

Development

Requirements

• Rust 1.70 or later
• Cargo

Building

cargo build --release

Testing

cargo test                # Run Rust tests
./test_install.sh        # Run installer tests

Release Process

The project follows semantic versioning and maintains synchronization between Cargo.toml versions and git tags.

To create a new release:

1. Use the version bump script:

./scripts/bump_version.sh 1.0.0  # Replace with your version

2. Review the changes:

git show HEAD

3. Push the changes:

git push origin main v1.0.0  # Replace with your version

The CI/CD pipeline will:

• Verify that Cargo.toml version matches the git tag
• Run all tests
• Build binaries for all supported platforms
• Generate SHA256 checksums
• Create a GitHub release
• Upload all assets

Development Guidelines

• Follow Test-Driven Development (TDD) practices
  • Write tests first before implementing new features
  • Ensure each new feature or bug fix has corresponding tests
  • Keep test coverage high and meaningful
• All code changes should maintain backward compatibility with existing templates
• Follow Rust best practices and idiomatic code patterns
• Ensure all templates follow Docker best practices:
  • Use multi-stage builds where appropriate
  • Include proper OCI labels
  • Follow principle of least privilege (run as non-root user)
  • Include proper documentation
• Always ensure Cargo version matches git tag for releases

License

MIT License