PHPackages                             yejune/bootapp - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. yejune/bootapp

ActiveLibrary[Utility & Helpers](/categories/utility)

yejune/bootapp
==============

0.2.124(3y ago)10GoPHP >=8

Since Jun 9Pushed 5mo agoCompare

[ Source](https://github.com/yejune/bootapp)[ Packagist](https://packagist.org/packages/yejune/bootapp)[ RSS](/packages/yejune-bootapp/feed)WikiDiscussions main Synced today

READMEChangelog (10)Dependencies (7)Versions (121)Used By (0)

bootapp
=======

[](#bootapp)

Docker CLI Plugin for multi-project Docker networking made easy.

Automatically manages:

- Unique subnet allocation per project (prevents conflicts)
- /etc/hosts entries for containers with DOMAIN configuration
- **SSL certificates** for domains in `SSL_DOMAINS` (auto-generated, system trusted)
- Smart route setup for macOS (checks connectivity before adding routes)

Installation
------------

[](#installation)

### Method 1: Using Homebrew (macOS)

[](#method-1-using-homebrew-macos)

```
brew install yejune/tap/bootapp
```

Homebrew automatically:

- Downloads and builds the latest version
- Installs as Docker CLI plugin (`docker bootapp`)
- Installs standalone binary (`bootapp`)
- Checks dependencies

### Method 2: Using install script (Linux/macOS)

[](#method-2-using-install-script-linuxmacos)

```
# Clone the repository
git clone https://github.com/yejune/bootapp.git
cd bootapp

# Run install script
bash install.sh
```

The install script automatically:

- Checks for Go and Docker
- Builds the binary
- Installs to `~/.docker/cli-plugins/bootapp` (Docker plugin)
- Installs to `/usr/local/bin/bootapp` (standalone binary)
- Checks platform-specific dependencies

### Method 3: Using go install

[](#method-3-using-go-install)

```
go install github.com/yejune/bootapp@latest
bootapp install
```

Or build locally:

```
git clone https://github.com/yejune/bootapp.git
cd bootapp
go build
./bootapp install
```

The `install` command automatically:

- Copies binary to `~/.docker/cli-plugins/bootapp`
- Installs standalone binary to `/usr/local/bin/bootapp`
- Sets executable permissions
- Checks platform dependencies

### Method 4: Manual installation

[](#method-4-manual-installation)

```
make build
cp build/bootapp ~/.docker/cli-plugins/bootapp
chmod +x ~/.docker/cli-plugins/bootapp
sudo cp build/bootapp /usr/local/bin/bootapp
sudo chmod +x /usr/local/bin/bootapp
```

Usage
-----

[](#usage)

### Start containers

[](#start-containers)

```
# Auto-detect docker-compose.yml
docker bootapp up

# Specify compose file
docker bootapp -f docker-compose.local.yml up
```

If multiple compose files are found, you'll be prompted to select interactively:

```
Select compose file:
▸ docker-compose.yml
  docker-compose.local.yml
  docker-compose.prod.yml

Use ↑/↓ arrows to navigate, Enter to select

```

Supported file patterns:

- `docker-compose.yml`, `docker-compose.yaml`
- `docker-compose.*.yml`, `docker-compose.*.yaml` (e.g., docker-compose.local.yml)
- `compose.yml`, `compose.yaml`

Options:

- `-d, --detach`: Run in background (default: true)
- `--no-build`: Don't build images
- `--pull`: Pull images before starting
- `-F, --force-recreate`: Force recreate containers + regenerate SSL certificates

This will:

1. Allocate unique subnet for the project (172.18-31.x.x range)
2. Parse docker-compose file for DOMAIN/SSL\_DOMAINS configuration
3. **Generate SSL certificates** for `SSL_DOMAINS` (if not exists)
4. **Install certificates to system trust store** (macOS Keychain / Linux ca-certificates)
5. Start containers with docker-compose up
6. Discover container IPs from default compose network
7. Add /etc/hosts entries for containers with domain config
8. Setup routing if needed (macOS)

### Stop containers

[](#stop-containers)

```
docker bootapp down
docker bootapp -f docker-compose.local.yml down
```

Options:

- `-v, --volumes`: Remove volumes
- `--remove-orphans`: Remove orphan containers
- `--keep-hosts`: Keep /etc/hosts entries
- `--remove-config`: Remove project from global config

### List projects

[](#list-projects)

```
docker bootapp ls
```

Domain Configuration
--------------------

[](#domain-configuration)

### Supported Environment Variables

[](#supported-environment-variables)

All of these environment variables are used for both:

- **Host machine access** (/etc/hosts)
- **Container-to-container access** (Docker network aliases)

Supported variables (duplicates removed, each supports single, comma, space, or newline separated values):

- `DOMAIN`
- `DOMAINS`
- `SSL_DOMAINS`
- `APP_DOMAIN`
- `VIRTUAL_HOST` (nginx-proxy compatible)

```
services:
  app:
    image: nginx
    environment:
      SSL_DOMAINS: |
        myapp.local
        www.myapp.local

  db:
    image: mysql:8
    environment:
      DOMAIN: db.local db-backup.local

  redis:
    image: redis
    # No DOMAIN = no /etc/hosts entry (IP only)
```

### Container-to-Container Communication

[](#container-to-container-communication)

Domains set via `DOMAIN`/`DOMAINS` are automatically registered as Docker network aliases, allowing containers to reach each other:

```
services:
  db:
    image: mariadb
    environment:
      DOMAIN: db.local db-delivery.local

  api:
    image: nginx
    environment:
      DOMAIN: api.local
    # api can reach db via: db.local or db-delivery.local
    # db can reach api via: api.local
```

This replaces the deprecated `external_links` and works automatically with Docker's built-in DNS.

### Traefik Labels

[](#traefik-labels)

Traefik router rules are also supported:

```
services:
  web:
    image: nginx
    labels:
      - "traefik.http.routers.web.rule=Host(`web.local`)"
      # Multiple hosts supported:
      - "traefik.http.routers.api.rule=Host(`api.local`) || Host(`api2.local`)"
      # Or comma-separated:
      - "traefik.http.routers.app.rule=Host(`app.local`, `www.app.local`)"
```

### Result

[](#result)

Only services with explicit domain configuration get /etc/hosts entries:

```
## bootapp:myproject
172.18.0.2    myapp.local
## bootapp:myproject
172.18.0.2    www.myapp.local
## bootapp:myproject
172.18.0.3    mysql.myapp.local

```

Services without DOMAIN config (like redis above) are not added to /etc/hosts.

SSL Certificates
----------------

[](#ssl-certificates)

### Automatic Generation

[](#automatic-generation)

bootapp automatically generates self-signed SSL certificates for domains specified in `SSL_DOMAINS`:

```
services:
  app:
    image: nginx
    environment:
      SSL_DOMAINS: myapp.test
    volumes:
      - ./var/certs:/etc/nginx/certs:ro
```

Certificates are:

- Generated in `./var/certs/` directory (`.crt`, `.key`, `.pem` files)
- Automatically trusted in system keychain (macOS) or ca-certificates (Linux)
- Valid for 10 years
- Include proper SAN (Subject Alternative Name) for browser compatibility

### Certificate Files

[](#certificate-files)

```
var/certs/
├── myapp.test.crt    # Certificate
├── myapp.test.key    # Private key
└── myapp.test.pem    # Combined cert + key

```

### Force Regenerate

[](#force-regenerate)

To delete and regenerate certificates:

```
docker bootapp -f docker-compose.local.yml up -F
```

The `-F` flag will:

1. Remove existing certificates from trust store
2. Delete local certificate files
3. Generate new certificates
4. Install to trust store
5. Force recreate containers

### nginx Configuration Example

[](#nginx-configuration-example)

```
server {
    listen 443 ssl;
    server_name myapp.test;

    ssl_certificate /etc/nginx/certs/myapp.test.crt;
    ssl_certificate_key /etc/nginx/certs/myapp.test.key;

    # ... rest of config
}
```

macOS Networking
----------------

[](#macos-networking)

**docker-mac-net-connect is required** for direct container IP access on macOS.

Docker Desktop runs containers inside a Linux VM, so macOS cannot directly access container IPs without a network tunnel.

### Installation

[](#installation-1)

```
brew install chipmk/tap/docker-mac-net-connect
sudo brew services start docker-mac-net-connect
```

bootapp will check for docker-mac-net-connect and show installation instructions if not found.

Linux
-----

[](#linux)

✅ **All features work natively on Linux!**

Linux support includes:

1. **Docker Networking**

    - Unique subnet per container
    - Direct container IP access (no additional tools needed)
2. **SSL Certificate Auto-generation & Trust**

    - Debian/Ubuntu: `update-ca-certificates`
    - RHEL/CentOS: `update-ca-trust`
    - Self-signed certificates automatically trusted system-wide
3. **Automatic /etc/hosts Management**

    - Domain → Container IP mapping
    - Auto register/cleanup per project
4. **Standalone Binary + Docker Plugin**

    - Use `bootapp` or `docker bootapp` commands

**Installation:**

```
# Requires Go
bash install.sh
# or
make build install
```

Unlike macOS, Linux doesn't need additional network tools (`docker-mac-net-connect`) - everything works out of the box!

Domain TLD Recommendations
--------------------------

[](#domain-tld-recommendations)

**Recommended TLDs:**

- `.test` - RFC 2606 reserved for testing ✅
- `.localhost` - Local only ✅
- `.internal` - Private networks ✅

**Avoid:**

- `.local` - Conflicts with macOS mDNS (slow DNS lookups)
- `.dev` - Google-owned, forces HTTPS
- `.app` - Google-owned, forces HTTPS

Configuration
-------------

[](#configuration)

Global configuration is stored in `~/.bootapp/projects.json`:

```
{
  "myproject": {
    "path": "/path/to/project",
    "subnet": "172.18.0.0/16",
    "domain": "myproject.local"
  },
  "another-project": {
    "path": "/path/to/another",
    "subnet": "172.19.0.0/16",
    "domain": "another.local"
  }
}
```

Each project gets a unique subnet (172.18.x.x through 172.31.x.x) to prevent IP conflicts between projects.

License
-------

[](#license)

MIT

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance48

Moderate activity, may be stable

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity70

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~19 days

Recently: every ~37 days

Total

118

Last Release

1436d ago

PHP version history (2 changes)0.2.8PHP >=5.5.9

0.2.95PHP >=8

### Community

Maintainers

![](https://www.gravatar.com/avatar/5c818085e28bfa56c39e978ee317fc88ffa1aa47450d78fc080a4de212d9e4e0?d=identicon)[peanut](/maintainers/peanut)

---

Top Contributors

[![yejune](https://avatars.githubusercontent.com/u/3735511?v=4)](https://github.com/yejune "yejune (17 commits)")

### Embed Badge

![Health badge](/badges/yejune-bootapp/health.svg)

```
[![Health](https://phpackages.com/badges/yejune-bootapp/health.svg)](https://phpackages.com/packages/yejune-bootapp)
```

###  Alternatives

[friendsofphp/php-cs-fixer

A tool to automatically fix PHP code style

13.5k245.4M24.0k](/packages/friendsofphp-php-cs-fixer)[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

19664.8M1.6k](/packages/drupal-core)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.4M196](/packages/sulu-sulu)[friendsoftypo3/content-blocks

TYPO3 CMS Content Blocks - Content Types API | Define reusable components via YAML

101466.4k45](/packages/friendsoftypo3-content-blocks)[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6941.5M396](/packages/drupal-core-recommended)[tempest/framework

The PHP framework that gets out of your way.

2.2k31.1k12](/packages/tempest-framework)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)