13.1 Docker for Local Development

Using Docker as a Local Development Environment

Docker can act as a complete local development environment instead of relying on software installed directly on your machine. The main idea is that you develop on your host system, but your application runs in containers that mimic one or more production-like environments.

Local Development vs Production

For local development, the focus is on fast feedback, easy iteration, and simple debugging. You usually want to rebuild and restart containers quickly, attach debuggers, and see log output on your terminal. You also want to avoid losing code or configuration when you stop containers.

In production, containers are usually more locked down and less chatty, and you rarely edit files inside them by hand. Locally, it is common to attach terminals, run additional tools inside containers, and mount your project folder so changes appear immediately.

The important idea is to keep the image similar to what will be used in production, but adapt how you run it during development. Typically this means the same base image and dependencies, but different entry commands, environment variables, or volumes.

Matching the Development Environment to Production

A key benefit of Docker in development is that you can run the same language runtime, libraries, databases, and system dependencies that exist in production. Instead of installing multiple versions of runtimes on your machine, you place those differences inside containers.

You might have one container for your web application, another for a database, and another for a cache. Locally, they run on your laptop as they would in the cloud, which helps catch configuration issues early. For example, mismatched database versions or missing system libraries are detected before deployment.

To keep the environments aligned, you usually build images from the same Dockerfiles used in production, then use different configuration at runtime. For instance, you might pass development credentials and debug flags as environment variables and keep production secrets out of your local setup.

Structuring a Project for Docker-based Development

A project that uses Docker for local development typically has a clear structure that separates application code, container configuration, and environment-specific files. Your application files live in the project directory, the Dockerfile defines the image, and additional configuration files define how containers are run during development.

This separation makes it easier to switch between running the app directly on your host and running it in Docker, because the core code and configuration remain the same. It also helps teams collaborate, because everyone can use a shared container configuration rather than manually installing tools.

In a typical setup, development-specific settings, such as verbose logging or debug mode, live in configuration files or environment files that are not used in production. The container image itself stays generic enough to be reused in multiple environments.

Using Local Source Code with Containers

For development, you usually keep your source code on your host machine and have the container read it from there. This way you edit files with your usual tools on your computer while the application runs in Docker and picks up changes.

The common pattern is to mount the project directory into the container as a volume. The container sees your files as if they were inside the image, but they are actually coming from your host. This makes it possible to change code without rebuilding the image every time.

When you mount source code, be careful with any folders that are created at build time. If a volume hides a directory that has already been populated inside the image, you may no longer see those built files. It is common to mount only the application source folders that need frequent editing and leave other paths untouched.

Development-only Dependencies and Tools

Some tools are useful only in development, such as file watchers, interactive debuggers, and extra logging utilities. You have a few ways to include them without polluting production images.

One approach is to install development tools in the same image behind configuration flags or separate commands, so they are only used when you run the container with development settings. Another approach is to create a second Dockerfile for development that extends the base image and adds tools that you never ship to production.

You can also choose to run certain tools on the host instead of inside the container, especially if they have better integration with your local editor or operating system. The key point is to keep a clear boundary between what is required to run the application and what is only there to assist development.

Environment Configuration for Local Work

When using Docker for local work, you usually need different configuration values than in production, such as local database addresses, sample credentials, or test API endpoints. Since configuration is external to images, you can easily swap these values between environments.

It is common to place local-only secrets and configuration in separate files that are not committed to version control. For example, you might define variables such as ports, feature flags, and debug behavior for local containers. These values are then passed to containers when they start.

You should keep local configuration and production configuration clearly separated to avoid accidentally using the wrong settings. Using different files, different compose profiles, or different environment variable files helps prevent mixing environments.

Working with Logs and Debugging Locally

One of the strengths of Docker in local development is that it is easy to observe and debug what your application is doing. Instead of connecting to remote systems, you can inspect everything on your machine.

You typically run containers in a way that streams logs to your terminal where you are starting them. This lets you see application logs, stack traces, and other messages in real time. You can also attach to containers that are already running and run additional commands to inspect their state.

For debugging, you may want to expose debug ports from containers to the host so that your editor or IDE can attach to the running process. This setup lets you place breakpoints and step through code that runs inside the container while using your usual development tools.

Managing Iteration Speed

A good Docker-based development workflow focuses on iteration speed. You want to move quickly between editing code, running tests, and seeing the application respond to changes.

Using mounted source code, caching build steps intelligently, and avoiding unnecessary work during container startup are all techniques to keep feedback loops short. You usually reserve image rebuilds for changes that affect dependencies or system-level behavior, not every code edit.

If starting containers becomes slow, you may need to adjust what happens during container initialization. For development, it can be better to separate expensive one-time setup from the main run command so you do not repeat that work on every restart.

Teams and Onboarding with Docker

In a team environment, Docker can greatly simplify onboarding and collaboration. Instead of each developer manually installing and configuring tools, everyone can share a defined container setup.

A new team member can often start by cloning the repository, building the images if needed, and starting the containers. Since the environment is described in files in the repository, it is easier to keep it consistent and to document usage patterns.

For this to work well, you must treat the container setup as part of the project. Configuration files, sample environment files, and any helper scripts should be kept up to date so that the documented way of starting the development environment actually matches what people use day to day.