Docker Compose: run your app, API and database together

Why describe the environment in a file

An application can depend on an API, a database, a cache and a processing process. Starting them separately with manual controls encourages forgetfulness and variations between people. Docker Compose brings together their definitions in a versioned configuration: images, networks, volumes and parameters. This configuration explains the structure of a reproducible environment. It does not replace architectural decisions or backup procedures, but provides a readable basis for starting, stopping and inspecting components. A new team member must be able to understand the services without reconstructing a series of forgotten commands.

Define services by responsibility

A Compose service describes a type of component, for example web, api or database. It can use an existing image or a local build. Give understandable names and separate processes that have different life cycles. The web application and a worker can share an image while having separate commands. Avoid putting all components in a single container just to reduce the number of services. This apparent simplification makes updates, logs and reboots more difficult to manage separately.

Organize networks and service names

Components in a shared Compose network can communicate using their service names. From the API, the database is generally not accessible under localhost, because this name refers to the API container itself. Configure the base service address and its internal port. Ports published on the host serve external access; they are not necessary for every internal communication. Separate networks when this provides a useful boundary. A public frontend may need to attach the API without the base being directly accessible from the browser or the Internet.

Manage variables, configurations and secrets

Compose allows you to provide parameters to services and use substituted values from the environment. Distinguish between what Compose interprets when reading the file and what the application receives in its container. A local file containing secrets should not be added to the repository just to make it easier to get started. Instead, provide an example without sensitive values ​​and document the required parameters. Check the values ​​by environment and rotation method. A missing configuration should produce an explicit error rather than silently connecting the application to the wrong database.

Understanding dependencies and availability

Starting the database before the API does not guarantee that the database is already accepting connections. A process can be active during an initialization or restore. Use relevant health checks and appropriate dependency conditions, while making the application capable of retrying temporary connections. Dependencies must remain limited to real needs. A failure of an optional tool should not cause the entire application to become unresponsive if a degraded mode is possible. Also check the behavior after a reboot while running, not just on first launch.

Preserve data and prepare backups

Declare the necessary volumes and identify the operations that can remove them. Shutting down or replacing a container does not have the same consequences as explicitly deleting data. Cleaning orders should be carefully documented. To back up a database, use a method consistent with its operation, not an improvised copy during writes. Keep backups in a separate location and control their retention period. A recovery to a separate environment provides concrete proof that the recovery plan can actually be used.

Example of API and base environment

A small platform can expose an API on the host and keep PostgreSQL on an internal network. The API receives its connection string and the database has a volume. Then add project-specific availability checks and migrations. The example below only illustrates the structure; secrets, versions, limits and application settings must be defined for the real environment. A demo configuration copied without analysis is not a production configuration.

services:
  api:
    image: my-company/api:release-42
    ports:
      - '8080:8080'
    environment:
      DB_HOST: database
  database:
    image: postgres:17
    volumes:
      - db-data:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD:?DB_PASSWORD is required}
volumes:
  db-data:

Separate development and production needs

In development, code edits and diagnostic tools facilitate changes. In production, we are looking for a tested artifact and a stable configuration. Avoid keeping the same debug access or source volumes there. Complementary files can express the differences without duplicating the entire definition. Document their order and the resulting values. Verify the final configuration before deployment. Just because an environment starts on a computer does not prove that the permissions, backups, and entry points are appropriate for an exposed server.

Know the limitations of Compose

Compose may be relevant for a development position or a limited deployment. It does not provide all the capabilities of a multi-host orchestration platform on its own. If the product requires placement on multiple machines, automatic recovery after loss of a host or advanced deployment policies, other infrastructure choices should be explored. However, don’t overcomplicate a small project without a real need. Compare expected availability, operating skills and total cost. The tool must match the team's ability to monitor and restore the system, including during an outage.

Deliver an environment that the team can exploit

A complete delivery describes how to start, verify, update, backup and restore. Add useful diagnostic commands and log locations, without giving away secrets. Test a clean install and update with existing data. Tuplify Studio can prepare Docker Compose environments for your applications and document their operation. The value does not come only from the YAML file: it lies in reproducible operation, clear responsibilities and a recovery procedure understood by the people who will ensure the continuity of the service.

Workshop: simulate an unavailable dependency

Start the environment then make the database unavailable in a test context. Observe the behavior of the API: understandable errors, limited retries and lack of log saturation. Restore the database and verify that the service returns to a usable state without hidden manipulation. Repeat with slow initialization on startup. Then check the ports accessible from the host and from other services. The goal is to check availability and exposure, not just the launch order. Document the results and limitations, because a dependency that falls after startup will not necessarily be handled by the conditions used to launch the containers alone.

Frequently asked questions: localhost and production

Why can't localhost find the database? In a container, it designates this container. Services normally use the name and internal port of their dependency on a common network.

Should the database port be published? Only if defined external access requires it. Internal communication does not require public exposure.

Is Compose banned in production? No: its suitability depends on the scope, expected availability and operation. Check what it provides and what it doesn't provide on its own, especially for multiple hosts. A small, well-maintained architecture may be preferable to a complex platform that the team does not know how to monitor or restore.