Part-DB-server/DEVELOPMENT.md

Development

Two methods are available for setting up a development environment.

1. Direct PHP environment
2. Docker based environment

Direct PHP Environment Setup

For setting up a native PHP development environment, you will need to install PHP, Composer, a database server (MySQL or MariaDB) and yarn (which needs a Node.js environment).

• Copy .env to .env.local and change APP_ENV to APP_ENV=dev. That way you will get development tools (Symfony profiler) and other features that will simplify development.
• Run composer install (without -o) to install PHP dependencies and yarn install to install frontend dependencies.
• Run yarn watch. The program will run in the background and compile the frontend files whenever you change something in the CSS or TypeScript files.
• For running Part-DB, it is recommended to use Symfony CLI. That way you can run a correctly configured webserver with symfony serve.

Docker Based Environment Setup

This document describes how to set up a complete Docker-based development environment for Part-DB.

Requirements

The following software is required:

• Docker
• Docker Compose
• Git

No local installation of PHP, Composer, Node.js, Yarn or a database server is required.

---

Development Environment

The development environment consists of two Docker images:

• Dockerfile – the upstream production image used as the development base.

• Dockerfile.dev – a lightweight development image layered on top of the production image that provides:

  • Composer development support
  • Node.js and Yarn
  • Live frontend rebuilding
  • Development PHP configuration
  • Automatic permission handling for bind-mounted source code

The development environment uses:

• SQLite database
• Symfony development mode
• Webpack Encore live asset rebuilding (yarn watch)

All application source code remains on the host machine.

---

Initial Setup

Clone the repository:

git clone https://github.com/Part-DB/Part-DB-server.git
cd Part-DB-server

Build the upstream production base image:

docker build --file Dockerfile --tag partdb-local-dev-base .

Build the development image:

docker compose -f compose.dev.yaml build

Install Composer dependencies:

docker compose -f compose.dev.yaml run --rm partdb composer install

Verify that Symfony is correctly configured:

docker compose -f compose.dev.yaml run --rm partdb php bin/console about

The output should report:

Environment    dev
Debug          true

Build the frontend assets:

docker compose -f compose.dev.yaml run --rm assets \
    sh -lc 'yarn install --network-timeout 600000 && yarn build'

Create the development database:

docker compose -f compose.dev.yaml run --rm partdb \
    php bin/console doctrine:migrations:migrate

During the initial migration an administrator account is created.

The output contains the generated password:

[warning] The initial password for the "admin" user is: ********

Record this password for the initial login.

Start the development environment:

docker compose -f compose.dev.yaml up -d partdb assets

Confirm both services are running:

docker compose -f compose.dev.yaml ps

Inspect the application logs:

docker compose -f compose.dev.yaml logs --tail=100 partdb

Inspect the frontend build logs:

docker compose -f compose.dev.yaml logs --tail=100 assets

Open Part-DB in your workstation browser:

http://localhost:8080/

---

Daily Development Workflow

Start the development environment:

docker compose -f compose.dev.yaml up -d

Restart the services:

docker compose -f compose.dev.yaml restart

Check service status:

docker compose -f compose.dev.yaml ps

Watch the application log:

docker compose -f compose.dev.yaml logs -f partdb

Watch the frontend asset compiler:

docker compose -f compose.dev.yaml logs -f assets

Stop the development environment:

docker compose -f compose.dev.yaml down

---

Composer

Install or update PHP dependencies:

docker compose -f compose.dev.yaml run --rm partdb composer install

Run any Composer command:

docker compose -f compose.dev.yaml run --rm partdb \
    composer <command>

Examples:

docker compose -f compose.dev.yaml run --rm partdb \
    composer update

docker compose -f compose.dev.yaml run --rm partdb \
    composer require vendor/package

---

Symfony Console

Run any Symfony command:

docker compose -f compose.dev.yaml run --rm partdb \ 
    php bin/console <command>

Examples:

docker compose -f compose.dev.yaml run --rm partdb \
    php bin/console cache:clear

docker compose -f compose.dev.yaml run --rm partdb \
    php bin/console about

---

Frontend Development

The assets service runs yarn watch and automatically rebuilds frontend assets whenever CSS or TypeScript files change.

To monitor the asset compiler:

docker compose -f compose.dev.yaml logs -f assets

To perform a one-off production build:

docker compose -f compose.dev.yaml run --rm assets yarn build

---

Testing

To run phpunit testing:

docker compose -f compose.dev.yaml run --rm partdb php bin/phpunit <test file>

To run code coverage test:

docker compose -f compose.dev.yaml run --rm \
    -e XDEBUG_MODE=coverage partdb php bin/phpunit --coverage-text \
    <test file>

Examples:

docker compose -f compose.dev.yaml run --rm partdb php bin/phpunit \
  tests/Services/ImportExportSystem/BOMImporterTest.php

docker compose -f compose.dev.yaml run --rm -e XDEBUG_MODE=coverage \
    partdb php bin/phpunit --coverage-text \
    tests/Services/ImportExportSystem/BOMImporterTest.php

---

Database

The development environment uses SQLite.

The database is stored on the host at:

var/db/app.db

The database is not removed when containers are recreated.

Run migrations only when:

• creating a new development environment
• new Doctrine migrations have been added
• the SQLite database has been deleted

Run migrations:

docker compose -f compose.dev.yaml run --rm partdb \
    php bin/console doctrine:migrations:migrate

---

Logs

Application logs:

docker compose -f compose.dev.yaml logs -f partdb

Frontend logs:

docker compose -f compose.dev.yaml logs -f assets

---

Docker Images

The development environment uses two images.

Base image

Built from the upstream Dockerfile:

docker build --file Dockerfile --tag partdb-local-dev-base .

This image only needs rebuilding when:

• the upstream Dockerfile changes
• PHP packages change
• system packages change

Development image

Built from Dockerfile.dev:

docker compose -f compose.dev.yaml build

Rebuild this image after changing:

• Dockerfile.dev
• compose.dev.yaml
• .docker/dev/

---

Troubleshooting

Rebuild the development image

docker compose -f compose.dev.yaml build
docker compose -f compose.dev.yaml up -d --force-recreate

View container logs

docker compose -f compose.dev.yaml logs -f partdb

docker compose -f compose.dev.yaml logs -f assets

Remove containers

docker compose -f compose.dev.yaml down

Clean generated files

rm -rf \
    vendor \
    node_modules \
    var/cache \
    var/log \
    var/db \
    var/share \
    public/build \
    public/bundles

The tracked files under uploads/ and public/media/ should not be removed.

---

Notes

The Docker development environment intentionally differs from the native development workflow described in CONTRIBUTING.md.

Specifically:

• No .env.local file is required.
• Symfony configuration is supplied through Docker environment variables.
• No local PHP installation is required.
• No local Composer installation is required.
• No local Node.js or Yarn installation is required.
• No local database server is required.
• Live frontend rebuilding is provided automatically by the assets service.