Docs Linux-first development Build. Run. Control.

Documentation

PIT is a Linux-first local dev environment engine. This documentation focuses on what already exists and what’s stable: runtime layout, sockets, and clean start/stop behavior.

What is PIT

PIT is a portable local dev engine that orchestrates services like Nginx and PHP-FPM with a strict focus on: predictable runtime paths, stable sockets, and clean start/stop.

Control

Lifecycle hygiene

No zombie processes.

Isolation

Projects vs tools

Separate sockets & runtime.

Predictability

Paths & logs

Deterministic cleanup.

Project status

This documentation intentionally avoids promises. Only include what your current engine actually supports.

Current focus

Linux development

Stable runtime + sockets + service control.

Docs policy

No fake installers

No “curl | bash” until it exists.

Quickstart (Linux dev)

Generic, valid steps for a Go-based engine on Linux. Adjust names/paths to your repo structure.

$ git clone <https://github.com/azdharsyahputra/pit.git>
$ cd pit
$ go mod tidy
$ go run ./cmd/pit up

# when done
$ go run ./cmd/pit down

If you ship a binary later, replace go run with ./pit.

User guide

Core concepts that matter for stability and day-to-day workflow.

Runtime layout

PIT should own a single runtime directory for all generated files: sockets, logs, and process state.

runtime/
  nginx/
  php/
  _tools/
    php/
logs/

Tools runtime

Tools should not share pools/sockets with projects. Keep them isolated to prevent coupling.

runtime/_tools/php/php-fpm.sock

Nginx integration

Keep Nginx config predictable by using include directories owned by PIT.

include conf.d/projects/*.conf;
include conf.d/tools/*.conf;

PHP-FPM integration

Use Unix sockets for local development. Separate sockets for projects vs tools.

runtime/php/php-fpm.sock
runtime/_tools/php/php-fpm.sock

Configuration

Keep configuration small and opinionated. One source of truth: engine.json.

engine.json (example)

This is an example schema. Only keep fields you actually implement.

{
  "basePath": "/home/your-user/pit",
  "httpPort": 80,
  "projectsDir": "/home/your-user/code",
  "php": {
    "default": "8.3",
    "projectSocket": "/runtime/php/php-fpm.sock",
    "toolsSocket": "/runtime/_tools/php/php-fpm.sock"
  },
  "nginx": {
    "confDir": "/nginx/conf",
    "includeProjects": "/nginx/conf.d/projects/*.conf",
    "includeTools": "/nginx/conf.d/tools/*.conf"
  }
}

Paths & sockets

PIT should generate and own all sockets under runtime so cleanup is deterministic.

• Project socket: runtime/php/php-fpm.sock
• Tools socket: runtime/_tools/php/php-fpm.sock
• Prefer unix sockets for local dev.

Logs & troubleshooting

Keep logs boring and searchable. Two places matter: Nginx error log and PHP-FPM log.

Common issue

Permission denied in runtime

Ensure PIT creates runtime folders with correct ownership. Avoid mixing sudo and user runs.

Common issue

Bad gateway

Usually means Nginx can’t reach the PHP-FPM socket. Verify socket path and file permissions.

FAQ

Short answers. No marketing fluff.

Q. Why PIT instead of XAMPP/Laragon?

A. PIT focuses on lifecycle hygiene and predictability: stable runtime paths, strict socket separation, and clean start/stop behavior. The goal is fewer “mysterious states” during development.

Q. Does PIT support Windows/macOS?

A. The current focus is Linux development. Other platforms will be documented only when they are truly supported.

Q. Why use Unix sockets for PHP-FPM?

A. For local dev, sockets are fast and avoid port collisions. PIT uses predictable socket paths so routing stays stable.

Q. I got “permission denied” in runtime. What should I do?

A. Make sure the runtime directory is owned by your user. Avoid running PIT with sudo sometimes and non-sudo other times.

Back to the pit wall

Return to the landing page or support development.

Home Sponsor