Docker Infrastructure & Tooling
Relevant source files
The following files were used as context for generating this wiki page:
The Docker infrastructure and associated tooling provide a standardized development and runtime environment for the ProductCompare modular monolith. The system leverages Docker Compose to manage stateful dependencies while utilizing Nix flakes for reproducible toolchain management.
This infrastructure is designed to support a Phoenix-based Elixir backend and a React-based frontend, ensuring consistency across local development, testing, and Continuous Integration (CI) environments.
Sources: README.md:1-25, ARCHITECTURE.md:1-15
Core Infrastructure Components
The project utilizes a hybrid approach to environment management, separating stateful services (managed by Docker) from the application runtime and build tools (managed by Nix and Bun).
Containerized Services
The primary stateful component is the PostgreSQL database, which is containerized to ensure version parity across all environments.
| Service | Technology | Version | Purpose |
|---|---|---|---|
| Database | PostgreSQL | 18 | Durable datastore for all relational facts and UUIDv7 generation. |
| Development Shell | Nix | N/A | Reproducible Elixir/Erlang/Phoenix toolchain. |
| Frontend Runtime | Bun | N/A | Package management and SSR execution for assets. |
Sources: README.md:5-15, backend_starting_guide.md:1-15, 2026-03-03-product-compare-backend-mvp-plan.md:5-15
Development Workflow Flowchart
The following diagram illustrates the sequence for initializing the development environment using the project's infrastructure tools.
The workflow prioritizes a "Nix-first" approach where the toolchain is loaded before interacting with containerized resources.
Sources: README.md:17-30
Database Infrastructure
The database layer is the only durable datastore in the architecture. Docker is used to provide a PostgreSQL 18 environment specifically to support native uuidv7() functionality and high-precision timestamps.
Connection Configuration
The application environment variables are wired to the Docker container's environment. By default, the database is exposed on localhost:5433 to avoid conflicts with standard system-level PostgreSQL installations.
- Runtime: Phoenix/Ecto
- Default Port: 5433
- Persistence: Named Docker volumes are used for the
dbservice to ensure data persists across container restarts.
Sources: README.md:27-30, 2026-03-03-product-compare-backend-mvp-plan.md:75-85
Data Modeling Requirements
The infrastructure supports specific Postgres requirements defined in the backend architecture:
- UUIDv7 Support: Native support in Postgres 18+ for
entropy_idcolumns. - Microsecond Precision: Configured via
:utc_datetime_usecfor all timestamp fields. - Relational Defaults: Bigint primary keys used for internal FK targets, while
entropy_id(UUID) is used for external/global identification.
Sources: backend_starting_guide.md:10-25, 2026-03-03-product-compare-backend-mvp-plan.md:110-120
Build & Tooling Integration
The project integrates several toolsets into its infrastructure to manage the lifecycle of the application from development to CI.
Backend Tooling (Mix)
Mix is the primary build tool used within the Nix-provided environment to orchestrate the backend.
| Command | Description |
|---|---|
mix setup | Installs dependencies and initializes the Docker-based database. |
mix typecheck | Runs Dialyzer and strict typespec checks. |
mix precommit | Hard gate: compiles with warnings-as-errors, runs tests, and formats code. |
mix ci | Executes the full integration suite. |
Sources: README.md:38-45, backend_starting_guide.md:180-195
Frontend Tooling (Bun/Vite)
The frontend, located in the assets/ directory, uses Bun as the package manager and runner, integrated with Vite for building and HMR (Hot Module Replacement).
The frontend tooling handles the compilation of StyleX styles and Relay GraphQL fragments.
Sources: assets/package.json:5-15, ARCHITECTURE.md:10-20
Testing Infrastructure
The infrastructure supports three distinct layers of testing, coordinated through Docker and Mix.
- SQL Sandbox: Integrated with
DataCase, allowing concurrent tests to run against the Dockerized PostgreSQL instance using ownership patterns. - E2E Testing: Playwright is used for end-to-end browser testing, simulating GraphQL-backed auth flows.
- Static Analysis: Dialyzer and Elixir compiler gates are enforced via the
mix precommittool.
Sources: backend_starting_guide.md:160-175, assets/package.json:10-20
Summary
The ProductCompare infrastructure utilizes Docker Compose to manage stateful PostgreSQL 18 services, ensuring the availability of modern features like native UUIDv7. This is complemented by Nix for toolchain reproducibility and Bun for frontend asset orchestration. This multi-layered tooling approach ensures that the "modular monolith" architecture remains stable across various development and deployment contexts.