Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
176 lines (127 loc) · 4.83 KB

CONTRIBUTING.md

File metadata and controls

176 lines (127 loc) · 4.83 KB
Raw

Contributing to glpi-docker-compose-stack

Thanks for your interest in contributing! This repository packages GLPI as a hardened, self-contained Docker Compose stack: a single-purpose glpi-php-fpm image plus the surrounding services (MariaDB, Valkey, nginx, the ofelia scheduler and the phpbu backup job).

Development Setup

Prerequisites

  • Docker with the Buildx and Compose plugins
  • Git
  • (optional) pre-commit for local lint hooks

Quick start

git clone https://github.com/netresearch/glpi-docker-compose-stack.git
cd glpi-docker-compose-stack

make init     # bootstrap .env (random DB passwords, idempotent)
make up       # start the stack (detached)
make health   # aggregated health of every service
make logs     # tail logs
make down     # stop (volumes preserved)

make help lists every target.

Building the image

# Local single-arch image (glpi-php-fpm:local) via the Makefile
make build

# …or via the bake file directly (glpi-php-fpm:dev, host arch, loaded)
docker buildx bake dev

docker run --rm glpi-php-fpm:dev php -v

The released multi-arch image is produced from the same docker-bake.hcl glpi target (see Release Process).

Making Changes

Branch naming

  • feat/ — new features
  • fix/ — bug fixes
  • docs/ — documentation
  • security/ — security improvements
  • chore/ — tooling / maintenance

Commit messages

Follow Conventional Commits:

type(scope): short description

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, test, chore, ci.

Examples:

feat(compose): add Caddy reverse-proxy overlay
fix(entrypoint): repair volume ownership before privilege drop
docs(readme): document GLPI_HTTP_PORT loopback default

Testing

Run the same checks CI runs, locally:

# Lint everything (hadolint + shellcheck + yamllint, no local installs)
make lint
# …or, if you use pre-commit:
pre-commit run --all-files

# Validate the bake file resolves
docker buildx bake --print

# Image-surface check (container-structure-test)
make test-image

# GLPI's own phpunit suite (slow, builds the tester stage)
make test-glpi

# Regression suite for the bin/ helper scripts
make test-bats

# Validate the Compose configuration
docker compose config --quiet

# Overlay hardening (run when you touch examples/*.yml)
./tests/lint/hardening-check.sh

Pull Request Process

flowchart LR
    A[Fork / branch] --> B[Develop]
    B --> C[Test + Lint]
    C --> D[PR]
    D --> E{Review}
    E -->|Approved| F[Merge]
    E -->|Changes| B
Loading
  1. Fork the repository (or branch, if you have access).
  2. Create a topic branch from main.
  3. Make your changes.
  4. Test + lint with the commands above.
  5. Open a pull request and fill in the template.

PR checklist

  • make lint (hadolint, shellcheck, yamllint) and actionlint are clean
  • docker buildx bake --print validates the bake file
  • The image builds (make build)
  • make test-bats passes
  • make test-image passes
  • docker compose config validates
  • ./tests/lint/hardening-check.sh passes (if examples/ changed)
  • No new critical/high vulnerabilities (Trivy)
  • Documentation updated if behavior changed

Release Process

Releases are automated. Tags use bare semver, no v prefix (matching the bundled GLPI version):

git tag -s 11.0.8 -m "11.0.8"   # signed tag
git push origin 11.0.8

release.yml then builds the multi-arch image via docker-bake.hcl, pushes <version> / <major.minor> / <major> / latest, cosign-signs each tag, and publishes a GitHub Release with categorized notes.

Code Style

  • Dockerfile — multi-stage, minimal layers, non-root, OCI labels; follow hadolint (.hadolint.yaml).
  • HCL / YAML — 2-space indentation (.editorconfig); keep docker-bake.hcl targets grouped and documented.
  • Shell — set -euo pipefail; keep it shellcheck-clean.
  • GitHub Actions — pin third-party actions by commit SHA with a trailing # vX.Y.Z comment; reference netresearch/.github reusable workflows at @main (never SHA-pinned).

Getting Help

License

By contributing, you agree that your contributions are licensed under this repository's split licensing: MIT for code and code-shaped configuration, CC-BY-SA-4.0 for prose and documentation. See LICENSE-MIT and LICENSE-CC-BY-SA-4.0.