https://github.com/utensils/essex
Essex - Boilerplate for Docker Based Projects
https://github.com/utensils/essex
boilerplate containers docker docker-builder docker-container docker-template docker-templates dockerfile dockerfile-generator dockerfiles dockerfiles-linux generator linux makefile oci project template tools
Last synced: 2 months ago
JSON representation
Essex - Boilerplate for Docker Based Projects
- Host: GitHub
- URL: https://github.com/utensils/essex
- Owner: utensils
- License: mit
- Created: 2018-04-22T06:46:39.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2025-01-30T00:00:39.000Z (2 months ago)
- Last Synced: 2025-01-30T00:19:13.518Z (2 months ago)
- Topics: boilerplate, containers, docker, docker-builder, docker-container, docker-template, docker-templates, dockerfile, dockerfile-generator, dockerfiles, dockerfiles-linux, generator, linux, makefile, oci, project, template, tools
- Language: Rust
- Homepage:
- Size: 43.9 KB
- Stars: 36
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-docker - essex - Boilerplate for Docker Based Projects: Essex is a CLI utility written in bash to quickly setup clean and consistent Docker projects with Makefile driven workflows. [@jamesbrink](https://github.com/jamesbrink) (Docker Images / Builder)
- awesome-docker - essex - Boilerplate for Docker Based Projects: Essex is a CLI utility written in bash to quickly setup clean and consistent Docker projects with Makefile driven workflows. [@jamesbrink](https://github.com/jamesbrink) (Docker Images / Builder)
- awesome-docker - essex - Boilerplate for Docker Based Projects: Essex is a CLI utility written in bash to quickly setup clean and consistent Docker projects with Makefile driven workflows. [@jamesbrink](https://github.com/jamesbrink) (Docker Images / Builder)
- awesome-docker - essex - Boilerplate for Docker Based Projects: Essex is a CLI utility written in bash to quickly setup clean and consistent Docker projects with Makefile driven workflows. [@jamesbrink](https://github.com/jamesbrink) (Docker Images / Builder)
README
# 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)
```bash
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:
```bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc # or restart your terminal
```
### From Source
```bash
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:
```bash
# 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`:
```bash
source ~/.local/share/bash-completion/completions/essex.bash
```
3. Reload your shell or source the file:
```bash
source ~/.bashrc
```
#### Zsh
1. Create the completion directory and generate the script:
```bash
mkdir -p ~/.zfunc
essex completion zsh > ~/.zfunc/_essex
```
2. Add to your `~/.zshrc`:
```zsh
fpath=(~/.zfunc $fpath)
autoload -Uz compinit
compinit
```
3. Reload your shell or source the file:
```bash
source ~/.zshrc
```
#### Testing Completion
After installation, you can test the completion by typing:
```bash
essex # Shows available commands (list, new, completion, help)
essex new # Shows available templates
essex completion # Shows supported shells (bash, zsh)
```
## Usage
```bash
# 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
```bash
cargo build --release
```
### Testing
```bash
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:
```bash
./scripts/bump_version.sh 1.0.0 # Replace with your version
```
2. Review the changes:
```bash
git show HEAD
```
3. Push the changes:
```bash
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