Docker Infrastructure

Relevant source files

The following files were used as context for generating this wiki page:

• docker-compose.yml
• README.md
• package.json
• CLAUDE.md
• src/index.ts

The Docker infrastructure for the Outmanage Backend provides a containerized environment for developing and deploying the TypeScript Express API and its associated MySQL database. It ensures environmental consistency across different stages of the software development lifecycle by encapsulating the application logic, runtime dependencies, and database services into isolated containers.

The infrastructure is primarily orchestrated using Docker Compose, which manages two main services: the api service (Node.js application) and the mysql service (database). It includes automated initialization scripts to handle database connectivity checks, migrations, and seeding, ensuring the system is ready for use immediately after the containers start.

Sources: docker-compose.yml, README.md:21-55, CLAUDE.md:18-25

Service Architecture

The project utilizes a multi-container architecture defined in the Docker Compose configuration. These services communicate over a private bridge network to ensure secure and isolated data exchange.

The diagram above illustrates the relationship between the API service and the database service within the internal Docker network.

Sources: docker-compose.yml:1-71

Component Specifications

Service	Image / Base	Purpose	Persistent Storage
api	Dockerfile (Node.js)	Runs the Express backend and Prisma ORM.	Bind mounts for ./src and ./prisma.
mysql	mysql:8.0	Provides the relational database for data storage.	Named volume mysql-data.

Sources: docker-compose.yml:3-66

Environment Configuration

The infrastructure relies heavily on environment variables to configure both the application and the database. These variables are typically loaded from .env files.

Core Environment Variables

Variable	Default Value	Description
NODE_ENV	development	Sets the application mode (development/production).
DATABASE_URL	mysql://user:password@mysql:3306/outmanage_db	Connection string for Prisma to reach the database container.
PORT	3000	The port on which the API listens inside and outside the container.
TZ	Asia/Jakarta	Sets the system timezone for consistent logging and data entry.
GEMINI_API_KEY	your_gemini_api_key_here	API key for Google Gemini AI integrations.

Sources: docker-compose.yml:10-21, CLAUDE.md:75-76, README.md:11-13

Initialization and Data Flow

The api container includes a robust startup command that manages the dependency on the MySQL database. It performs a "wait-for-it" pattern to ensure the database is fully accepting connections before attempting application logic.

Startup Sequence Logic

1. Wait Loop: The container sleeps for 10 seconds, then repeatedly checks port 3306 on the mysql host using nc (Netcat).
2. Environment Branching:
   • Production: Executes npx prisma migrate deploy to apply pending migrations without resetting data, followed by npm start.
   • Development: Executes npx prisma migrate reset --force to ensure a clean state, runs npm run seed to populate initial data, and finally starts npm run dev for hot-reloading.

Sources: docker-compose.yml:26-48, package.json:7-11

The sequence diagram shows the automated orchestration steps performed during the container boot process.

Sources: docker-compose.yml:26-48, README.md:35-50

Volume Management and Persistence

Persistence is handled differently for application code and database storage to support efficient development workflows.

• Development Bind Mounts: The ./src and ./prisma directories are mounted into the /app directory inside the container. This allows developers to see changes reflected in the containerized environment immediately without rebuilding the image.
• Database Volume: The mysql-data named volume is mapped to /var/lib/mysql in the database container. This ensures that even if the database container is removed or restarted, the actual data persists.

Sources: docker-compose.yml:23-25, 63-64, 68-69

Networking and Security

The services are connected via a bridge network named outmanage-network.

• Database Security: The MySQL container is configured with a default timezone of +07:00 and utf8mb4 character sets to support Indonesian logistics data correctly.
• Access Control: The API container is accessible via the host on the defined PORT, while the MySQL container exposes its port (3306) to the host, though primary interaction occurs internally within the Docker network.

Sources: docker-compose.yml:53-71, src/index.ts:130-134

Summary

The Docker infrastructure of the Outmanage Backend provides a highly automated, two-tier environment. By integrating Prisma migrations and seeding into the api service's startup command, the project reduces manual setup steps. The use of specific timezones (Asia/Jakarta) and health-check loops ensures that the system is both robust and localized for its intended logistics operations.