Finalizing Your Docker Project Structure: Organization Best Practices

Previously in this course, we explored managing secret configuration to keep our environment variables secure. Now that our services can securely talk to each other, it’s time to move out of the "prototype" phase and into a project structure that reflects professional standards.

As your application grows beyond a single script, dumping every Dockerfile and config file into the root directory becomes a liability. A chaotic layout makes it difficult for new team members to orient themselves and complicates your CI/CD pipeline. Today, we’re restructuring our project to ensure clarity and maintainability.

Principles of Project Organization

In a professional DevOps environment, the goal of your project structure is decoupling. You want the ability to build, test, and deploy each service independently without the risk of accidental cross-contamination.

We follow these core principles for containerized applications:

1. Service Isolation: Each microservice lives in its own subdirectory.
2. Dockerfile Proximity: The Dockerfile should reside inside the service directory it defines.
3. Centralized Orchestration: A single docker-compose.yml file sits at the root to coordinate the entire stack.
4. Configuration Separation: Keep non-code assets (like configuration files or environment templates) in dedicated folders.

The Standard Structure

Here is the recommended layout for a typical multi-service web application:

TEXT
my-app/
├── services/
│   ├── web-api/
│   │   ├── Dockerfile
│   │   ├── src/
│   │   └── package.json
│   └── data-worker/
│       ├── Dockerfile
│       └── main.py
├── config/
│   └── nginx.conf
├── .env.example
└── docker-compose.yml

Implementing the Structure

Let’s transition our current project to this layout. If you have been following along, you likely have your Dockerfile at the root. We need to move it into a services/web-api/ directory.

1. Create the directory: mkdir -p services/web-api
2. Move your files: Move your source code and Dockerfile into that folder.
3. Update the Compose file: Your docker-compose.yml needs to know that the build context has moved.

Update your docker-compose.yml to point to the new location:

YAML
services:
  web-api:
    build:
      context: ./services/web-api
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
  
  db:
    image: postgres:15
    # ... rest of your config

By setting the context to ./services/web-api, Docker now treats that directory as the root for all COPY commands in your Dockerfile. This is much cleaner than referencing files across parent directories.

Hands-on Exercise: Refactor Your Project

Your task for this lesson is to implement this structure in your current workspace:

1. Create a services/ directory and move your primary application code into a sub-folder (e.g., services/app).
2. Move your Dockerfile into that same sub-folder.
3. Update your docker-compose.yml file to reflect the new build: context path.
4. Run docker compose build to ensure the transition didn't break your image construction.

Common Pitfalls

• Deeply Nested Contexts: Avoid setting your build context to a parent directory (e.g., .) if your Dockerfile is deep in a sub-folder. This causes Docker to send the entire project to the daemon, which significantly slows down build times.
• Hardcoded Paths: Never use absolute paths (e.g., /home/user/project/...) in your docker-compose.yml or Dockerfile. Always use relative paths so the project remains portable.
• Mixing Secrets and Code: Never move your .env files into a directory that gets pushed to your code repository. Keep them at the root and ensure they are added to your .gitignore.

Frequently Asked Questions (FAQ)

Q: Should I have one Dockerfile per service? Yes. Best practices dictate that each image should be responsible for exactly one service or process.

Q: Does moving files affect my volumes? If you are using bind mounts, yes. You must update your volumes: mapping in docker-compose.yml to reflect the new path on your host machine.

Q: Why separate the config folder? It keeps your root directory clean and allows you to easily mount entire directories of configuration (like Nginx or database config files) into your containers.

Recap

By structuring your directories logically, you reduce "cognitive load" for anyone working on the project. We’ve moved from a flat, disorganized file system to a modular, service-oriented structure that isolates build contexts and centralizes orchestration. This structure is a prerequisite for more advanced topics like optimizing build cache and multi-stage builds.

Up next: We will tackle Optimizing Image Size, where we'll learn how to use multi-stage builds to keep our production images lean and secure.