@firestitch/app-docker

Local Docker development environment for Firestitch projects: Angular (Vite/ng serve with HTTPS), PHP-FPM, Nginx for /api/, and MySQL on the host.

Prerequisites

• Docker (Docker Desktop includes Docker Compose v2)
• MySQL running on the host on port 3306 (the container forwards a Unix socket so PHP can use DB_HOST=localhost against your host database)
• Node.js (for npx / running the launcher locally)

Expected project layout

Point --dir at the Firestitch app root (parent of frontend). That directory must include:

| Path | Role | |------|------| | frontend/package.json | Required; name drives the dev URL; optional config.port (default 5000) | | backend/ | PHP app (Composer install runs in-container if needed) | | framework/ | Shared framework code | | config.php | App config | | data/ | Writable app data |

The frontend should support ng serve with --configuration local and include @firestitch/app-tools (SSL key/cert paths used by the entrypoint).

Usage

Relative paths are resolved from the current working directory:

npx @firestitch/app-docker --dir ..

Note: The flag is --dir, not -dir.

From this repository

npm install
npm start

npm start runs the launcher with --dir ../ (adjust if your app root is elsewhere).

First-time setup on your machine

1. Hosts file — Add the line printed when the container starts, for example:

   127.0.0.1 your-app-name.local.firestitch.com

2. Browser — Open the URL shown in the logs (HTTPS, app name + port from frontend/package.json).

3. Stop — Ctrl+C stops Compose and runs docker compose down for this project.

How files are connected (mapped folders)

Docker uses bind mounts for almost everything: your project paths on disk are attached inside the container at /var/www/app/.... The exception is frontend/node_modules, which uses a named volume so npm install stays inside the Linux environment and does not mix with a host node_modules tree.

| In the container | On your machine (same files) | |------------------|-------------------------------| | /var/www/app/frontend (sources) | <project>/frontend — node_modules is not on the repo disk; it lives in a Docker volume so installs stay isolated inside Linux | | /var/www/app/data | <project>/data — includes data/temp |

backend/, framework/, and config.php are bind mounts only.

What it runs

• Builds and starts the image in docker/ (Fedora-based: PHP-FPM, Nginx, Node, Composer).
• Bind-mounts backend, frontend (sources), framework, config.php, and data; uses a named volume only for frontend/node_modules.
• Publishes the dev server port (from config.port or 5000) to the host.

Requirements summary

• Docker with Compose v2 (docker compose)
• Host MySQL on port 3306
• Valid Firestitch tree with frontend/package.json at the path given to --dir