Does the project run only on its author’s laptop? Make the first start reproducible

When one command turns into an hour of errors

The team tells a new developer to clone the repository, run one command, and start working. An hour later, the developer is sharing a third error screenshot. First, the runtime version is incompatible. Then an environment variable is missing. Finally, everyone discovers that one required service exists only on the original author’s laptop.

It is easy to treat this as a test of the newcomer’s attention or skills. A more useful question is whether the team can recreate the working environment without relying on knowledge stored in one person’s memory.

Containerization is often offered as the quick answer. However, the presence of a Dockerfile or another container definition does not prove that startup became easier. The team needs to test the path under the same conditions before and after the change.

Mohammad-Ali A’râbi gives a concrete example in Docker Blog: in 2015, he spent a full week trying to start a Django project and kept failing because of dependency conflicts. Several years later, at another company, he introduced Docker and CI/CD pipelines. This helps explain why developers turn to containerization, but it does not mean containers automatically remove every startup problem. Each team still needs to test the result on its own project.

Pass one: record the real starting point

Begin with a clean-room test. Use a new virtual machine, a separate laptop, or a disposable environment without the original author’s caches and local configuration.

Record the starting conditions:

• the operating system and machine architecture;
• everything installed before the repository is cloned;
• the branch and code version being tested;
• the point when the timer starts;
• the exact definition of success.

Success should be visible. For example, the application answers a readiness check, the required database migration completes, and a basic test suite passes. A running process is not enough: the application may still have no connection to its database or message queue.

Follow the README literally. For every stop, record the command, error, cause, fix, and time spent. Do not improve the instructions during this pass. You first need an honest picture. The resulting log will reveal hidden versions, files, ports, and manual steps.

What a container can capture—and what stays outside

A well-defined container image can capture the runtime, system packages, application dependencies, and startup command. This reduces accidental differences between laptops and can provide the same base for local work and CI.

A container does not contain the project’s entire world. Machine architecture, network access, external databases, file permissions, secrets, and compatible versions of connected services remain outside it. If the application silently expects a local file or a manually created queue, that problem will simply move into the new startup path.

Unstable image labels create another risk. If the same label produces different contents on different days, the reproducible environment disappears. Important components need deliberately selected versions and a documented update process.

Pass two: repeat the test under the same rules

After making changes, start again with a clean environment. Do not reuse images, caches, or configuration from the first pass.

The preferred path is short: install the declared prerequisites, clone the repository, create local configuration from a safe template, and run one documented command. A separate check command should report whether the application and its required services are ready.

CI should use the same core build and test steps. This does not mean a developer laptop and CI must be identical in every detail. They should not, however, build the application through unrelated scripts or resolve different sets of dependencies.

Compare the two passes by time to first success, number of stops, manual actions, and undocumented requirements. Then ask another person to repeat the result without spoken hints.

How to interpret common results

• It works locally but fails in CI. Look for a local cache, mounted file, different command, or dependency on a service running on the developer’s machine.
• CI works but a clean laptop fails. An essential preparation step may exist only in the CI configuration and be missing from the README.
• A rebuild suddenly breaks. Check for moving versions in base images and application dependencies.
• Startup requires copying a key into the image. Do not do this. A secret should be supplied at runtime through a team-approved mechanism and must not enter the build history.
• The container needs excessive privileges. Review file permissions and run its process without unnecessary rights.
• The instructions require many manual corrections. Automate repeatable steps or turn them into explicit checks with useful error messages.

One anti-pattern is treating a container as an archive of the author’s laptop. Another is hiding a long sequence of fragile actions behind one command without checking individual failures. A single command is useful only when its result is understandable and repeatable.

Leave a short runbook behind

The final first-run guide can fit on one page. Include declared prerequisites, one startup command, the readiness signal, names of required environment variables, common errors, and commands for stopping and cleaning the environment.

Also state how dependencies are updated, who owns the document, and when the team will repeat the clean-room test. Run the test again after changing the runtime, base image, or an important external service.

Containerization helped if the second pass became faster, more predictable, and closer to CI. If the number of hidden steps did not decrease, the team did not solve the problem—it only moved it. The goal is not to possess a container definition. The goal is to let the next person reach the same working result without guessing.

Sources

• Docker Blog — From the Captain’s Chair: Mohammad-Ali A’râbi: https://www.docker.com/blog/from-the-captains-chair-mohammad-ali-arabi/